@things-factory/headless-twin 10.1.278 → 10.1.280

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

@@ -1,264 +0,0 @@
-import type { ReferenceAdapter, SiteDescriptor } from './reference-adapter.js'
-import type { ReferenceMaster } from './reference-master.js'
-import { capabilitiesOf } from './reference-adapter.js'
-import { REFERENCE_STEPS, type ReferenceStep } from './reference-progress.js'
-
-/*
- * **커넥터 점검 하네스** — 실 원본에 붙여 「무엇이 채워지고 무엇이 비는가」를 한 번에 본다.
- *
- * ── 왜 필요한가 (2026-08-21) ────────────────────────────────────────────────
- * chef v1 커넥터를 만들 때 실 인스턴스(포천)에 붙이는 확인을 매번 손으로 했다 — curl 로 필드를 묻고,
- * 일회용 스크립트로 마스터를 읽고, 결과를 눈으로 셌다. 그 방식은 세 가지를 잃는다:
- *  · 같은 확인을 다음 커넥터에서 처음부터 다시 만든다.
- *  · 무엇을 확인했는지가 어디에도 남지 않는다.
- *  · **앱을 띄워야 알 수 있는 것**이 되어 버린다 — dev 서버가 남의 것이면 확인 자체가 막힌다.
- *
- * 그래서 어댑터 규약만 아는 자리에 둔다. 어댑터는 `testConnection` · `discoverSites` · `fetchMaster` ·
- * `openLiveFeed` 를 갖는 객체이고, 그 넷을 순서대로 부르는 일에 커넥터별 지식이 필요하지 않다.
- *
- * ── 무엇을 하지 않는가 ──────────────────────────────────────────────────────
- *  · **판단하지 않는다.** 「합격」을 매기지 않고 센 것을 그대로 낸다 — 무엇이 충분한지는 커넥터마다
- *    다르고, 그 판단은 체크리스트 문서가 한다.
- *  · **저장하지 않는다.** 트윈을 만들지도, 커서를 남기지도 않는다. 원본을 읽기만 한다.
- *  · **라이브는 부르지 않는 것이 기본이다.** 첫 주기는 전량 읽기이므로 실 운영 원본에 부담이 된다
- *    (포천은 로트 99,095 · 투입 290,688 · 재고 141,358건이다). 부를 때는 호출부가 명시한다.
- */
-
-/** 마스터 한 벌에서 센 것 — 커넥터와 무관한 자리 이름으로만 센다. */
-export interface MasterCounts {
-  locations: number
-  areas: number
-  equipment: number
-  materialDefinitions: number
-  operations: number
-  /** 생산 선언이 없으면 `undefined` — 0 과 구별한다(선언 자체가 없는 것과 비어 있는 것은 다르다). */
-  materials?: number
-  materialsWithHome?: number
-  routes?: number
-  recipes?: number
-  recipesWithRoute?: number
-  locationTypes?: number
-  resourceTypes?: number
-}
-
-export interface ProbeStep {
-  key: ReferenceStep | string
-  detail?: string
-  /** 그 단계가 끝난 시각까지 걸린 밀리초 — 어느 단계가 느린지 보이게 한다. */
-  elapsedMs: number
-}
-
-export interface ProbeReport {
-  adapter: string
-  /** 어댑터가 선언하고 **구현까지 있는** 능력. 선언만 있는 것은 여기 나오지 않는다. */
-  capabilities: string[]
-  connection?: { ok: boolean; readiness?: string; notes?: string[]; error?: string }
-  sites?: { siteId: string; name?: string }[]
-  /** 사이트마다 한 벌 — 마스터는 사이트 단위다. */
-  masters: {
-    siteId: string
-    steps: ProbeStep[]
-    counts?: MasterCounts
-    warnings: string[]
-    space?: unknown
-    identity?: unknown
-    /** 표본 — 눈으로 확인할 몇 건. 전체를 싣지 않는다(원본이 수천 건이다). */
-    samples?: { recipes?: unknown[]; routes?: unknown[]; locations?: unknown[] }
-    elapsedMs: number
-    error?: string
-  }[]
-  /** 라이브를 부른 경우에만 — 한 주기가 낸 기록을 종류별로 센다. */
-  live?: { records: number; byShape: Record<string, number>; samples: unknown[]; elapsedMs: number; error?: string }
-  /** 선언한 단계 중 **한 번도 보고되지 않은** 것. 선언해 두고 보내지 않으면 화면의 진행이 멈춘 것처럼 보인다. */
-  silentSteps?: string[]
-  /** 선언하지 않은 이름으로 보고한 단계. 표준 낱말 밖의 값은 화면이 번역할 수 없다. */
-  unknownSteps?: string[]
-}
-
-/** 기록의 모양을 이름 붙인다 — 커널 낱말로만 가린다(커넥터를 알 필요가 없다). */
-function shapeOf(r: any): string {
-  if (r?.inputQuantityList || r?.outputQuantityList) return 'transformation'
-  if (r?.taskId) return 'task'
-  if (r?.orderId) return 'order'
-  if (r?.quantityList || r?.epcList) return 'observation'
-  return 'other'
-}
-
-function countMaster(ref: ReferenceMaster): MasterCounts {
-  const m: any = ref
-  const d = m.productionSpec?.definition
-  return {
-    locations: m.locations?.length ?? 0,
-    areas: (m.locations ?? []).filter((l: any) => l.role === 'area').length,
-    equipment: m.equipment?.length ?? 0,
-    materialDefinitions: m.materialDefinitions?.length ?? 0,
-    operations: m.operations?.length ?? 0,
-    ...(d
-      ? {
-          materials: d.materials?.length ?? 0,
-          materialsWithHome: (d.materials ?? []).filter((x: any) => x.locationType).length,
-          routes: d.routes?.length ?? 0,
-          recipes: d.recipes?.length ?? 0,
-          recipesWithRoute: (d.recipes ?? []).filter((x: any) => x.route).length,
-          locationTypes: d.locationTypes?.length ?? 0,
-          resourceTypes: d.resourceTypes?.length ?? 0
-        }
-      : {})
-  }
-}
-
-const messageOf = (w: unknown): string => (typeof w === 'string' ? w : `${(w as any)?.code}: ${(w as any)?.message}`)
-
-/**
- * 사람이 읽는 줄로 자른다 — **자랐다는 사실을 함께 적는다.**
- *
- * 경고에 값 목록이 붙는다(어느 자리가 걸렀는지). 88건이면 UUID 88개가 한 줄에 쏟아져 보고를 읽을 수
- * 없게 된다. 그래서 사람용 출력에서만 자르고, 전체는 보고 객체(`--json`)에 그대로 남긴다.
- */
-const brief = (text: string, max = 300): string =>
-  text.length <= max ? text : `${text.slice(0, max)}… (${text.length}자 중 앞 ${max}자 — 전체는 보고 객체에 있다)`
-
-/**
- * 어댑터 한 벌을 실 원본에 붙여 본다.
- *
- * 실패를 던지지 않는다 — **어디까지 갔는지가 보고의 내용**이다. 연결이 안 되면 그 사실이, 마스터가
- * 실패하면 어느 단계에서 실패했는지가 보고에 남는다(예외로 끝나면 그 정보가 사라진다).
- */
-export async function probeReference(opts: {
-  adapter: ReferenceAdapter
-  config: any
-  /** 특정 사이트만 볼 때. 없으면 `discoverSites` 가 낸 전부. */
-  siteId?: string
-  /**
-   * 라이브 한 주기를 부를지. **기본은 부르지 않는다** — 첫 주기가 전량 읽기다.
-   * `waitMs` 만큼 기다린 뒤 멈춘다(주기가 끝나지 않았으면 그때까지 받은 것만 센다).
-   */
-  live?: { waitMs: number; sampleCount?: number }
-  /** 표본 건수 — 기본 3건. */
-  sampleCount?: number
-}): Promise<ProbeReport> {
-  const { adapter, config } = opts
-  const sampleCount = opts.sampleCount ?? 3
-  const report: ProbeReport = { adapter: adapter.type, capabilities: capabilitiesOf(adapter), masters: [] }
-
-  if (adapter.testConnection) {
-    try {
-      report.connection = (await adapter.testConnection(config)) as any
-    } catch (e: any) {
-      report.connection = { ok: false, error: e?.message ?? String(e) }
-    }
-    /* 연결이 안 되면 더 가지 않는다 — 그 뒤 실패는 모두 같은 원인의 반복이다. */
-    if (report.connection && report.connection.ok === false) return report
-  }
-
-  let sites: SiteDescriptor[] = []
-  try {
-    sites = adapter.discoverSites ? await adapter.discoverSites(config) : []
-  } catch (e: any) {
-    report.sites = []
-    report.masters.push({ siteId: '(사이트를 찾지 못했다)', steps: [], warnings: [], elapsedMs: 0, error: e?.message ?? String(e) })
-    return report
-  }
-  if (opts.siteId) sites = sites.filter(s => s.siteId === opts.siteId)
-  report.sites = sites.map(s => ({ siteId: s.siteId, name: s.name }))
-
-  const declared = new Set<string>(adapter.masterSteps ?? [])
-  const reported = new Set<string>()
-  const unknown = new Set<string>()
-
-  for (const site of sites) {
-    const t0 = Date.now()
-    const steps: ProbeStep[] = []
-    try {
-      const ref = await adapter.fetchMaster!(config, site, s => {
-        reported.add(String(s.key))
-        if (!(REFERENCE_STEPS as readonly string[]).includes(String(s.key))) unknown.add(String(s.key))
-        steps.push({ key: s.key, detail: s.detail, elapsedMs: Date.now() - t0 })
-      })
-      const m: any = ref
-      const d = m.productionSpec?.definition
-      report.masters.push({
-        siteId: site.siteId,
-        steps,
-        counts: countMaster(ref),
-        warnings: (m.warnings ?? []).map(messageOf),
-        space: m.space,
-        identity: m.identity,
-        samples: {
-          recipes: (d?.recipes ?? []).slice(0, sampleCount),
-          routes: (d?.routes ?? []).slice(0, sampleCount),
-          locations: (m.locations ?? []).slice(0, sampleCount)
-        },
-        elapsedMs: Date.now() - t0
-      })
-    } catch (e: any) {
-      /* 어느 단계까지 갔는지를 남긴다 — 그것이 다음에 볼 자리다. */
-      report.masters.push({ siteId: site.siteId, steps, warnings: [], elapsedMs: Date.now() - t0, error: e?.message ?? String(e) })
-    }
-  }
-
-  const silent = [...declared].filter(s => !reported.has(s))
-  if (silent.length) report.silentSteps = silent
-  if (unknown.size) report.unknownSteps = [...unknown]
-
-  if (opts.live && adapter.openLiveFeed && sites.length) {
-    const t0 = Date.now()
-    const got: unknown[] = []
-    try {
-      const stop = adapter.openLiveFeed(config, sites[0], rs => got.push(...rs))
-      await new Promise(r => setTimeout(r, opts.live.waitMs))
-      stop()
-      const byShape: Record<string, number> = {}
-      for (const r of got) byShape[shapeOf(r)] = (byShape[shapeOf(r)] ?? 0) + 1
-      report.live = {
-        records: got.length,
-        byShape,
-        samples: got.slice(0, opts.live.sampleCount ?? sampleCount),
-        elapsedMs: Date.now() - t0
-      }
-    } catch (e: any) {
-      report.live = { records: got.length, byShape: {}, samples: [], elapsedMs: Date.now() - t0, error: e?.message ?? String(e) }
-    }
-  }
-
-  return report
-}
-
-/** 보고를 사람이 읽는 줄로 — 화면이 아니라 터미널·로그가 읽는다. */
-export function formatProbeReport(r: ProbeReport): string {
-  const out: string[] = []
-  out.push(`커넥터 ${r.adapter} · 능력 ${r.capabilities.length ? r.capabilities.join(',') : '(없음)'}`)
-  if (r.connection) {
-    out.push(`연결 ${r.connection.ok ? 'ok' : '실패'}${r.connection.readiness ? ` · 읽기준비 ${r.connection.readiness}` : ''}`)
-    for (const n of r.connection.notes ?? []) out.push(`  · ${brief(n)}`)
-    if (r.connection.error) out.push(`  · ${r.connection.error}`)
-  }
-  for (const m of r.masters) {
-    out.push(`사이트 ${m.siteId} — ${(m.elapsedMs / 1000).toFixed(1)}초`)
-    for (const s of m.steps) out.push(`  [${(s.elapsedMs / 1000).toFixed(1)}s] ${s.key}${s.detail ? ` — ${s.detail}` : ''}`)
-    if (m.error) out.push(`  실패: ${m.error}`)
-    if (m.counts) {
-      const c = m.counts
-      out.push(
-        `  로케이션 ${c.locations}(존 ${c.areas}) · 설비 ${c.equipment} · 자재정의 ${c.materialDefinitions} · 공정 ${c.operations}`
-      )
-      if (c.materials !== undefined) {
-        out.push(
-          `  선언자재 ${c.materials}(보관 로케이션 있는 것 ${c.materialsWithHome}) · 경로 ${c.routes} · 레시피 ${c.recipes}(경로 붙은 것 ${c.recipesWithRoute})`
-        )
-      } else {
-        out.push('  생산 선언 없음 — 레시피가 하나도 성립하지 않았다')
-      }
-    }
-    for (const w of m.warnings) out.push(`  경고 ${brief(w)}`)
-  }
-  if (r.silentSteps?.length) out.push(`선언했으나 보고되지 않은 단계: ${r.silentSteps.join(', ')}`)
-  if (r.unknownSteps?.length) out.push(`표준 낱말 밖의 단계 이름: ${r.unknownSteps.join(', ')}`)
-  if (r.live) {
-    out.push(
-      `라이브 한 주기 — 기록 ${r.live.records}건 (${Object.entries(r.live.byShape).map(([k, v]) => `${k} ${v}`).join(' · ') || '없음'}) · ${(r.live.elapsedMs / 1000).toFixed(1)}초`
-    )
-    if (r.live.error) out.push(`  실패: ${r.live.error}`)
-  }
-  return out.join('\n')
-}

package/server/service/reference/reference-progress-channel.ts

@@ -1,26 +0,0 @@
-/*
- * The `twin-reference-progress` channel — **progress says whose import it is, and the filter asks.** Pure.
- *
- * The subscription filtered on `source` alone and checked only that the caller had some domain, so
- * anyone who knew a source name — and names like `sap-ewm-1710` are shared between tenants — received
- * another tenant's import progress, including its failure text. Same fix and same rule as
- * `engine/twin-state-channel.ts`.
- */
-
-export const REFERENCE_PROGRESS_TOPIC = 'twin-reference-progress'
-
-export interface ReferenceProgressPayload<M extends { source: string } = { source: string }> {
-  domainId: string
-  twinReferenceProgress: M
-}
-
-export function referenceProgressPayload<M extends { source: string }>(domainId: string, message: M): ReferenceProgressPayload<M> {
-  if (!domainId) throw new Error('referenceProgressPayload: domainId is required — import progress always belongs to a tenant')
-  return { domainId, twinReferenceProgress: message }
-}
-
-/** Passes only this tenant's progress for this source. */
-export function referenceProgressFilter(domainId: string, source: string) {
-  return (p: ReferenceProgressPayload | undefined): boolean =>
-    !!p && p.domainId === domainId && p.twinReferenceProgress?.source === source
-}

package/server/service/reference/reference-progress-subscription.ts

@@ -1,78 +0,0 @@
-/*
- * 유입 진행 구독 — **트윈을 만드는 동안 무엇을 하고 있는지 화면이 안다.**
- *
- * 마스터 읽기는 원본에 여러 질의를 보내는 긴 작업이고, 그 사이 화면은 아무것도 알 수 없었다. 단계를
- * 아는 것은 어댑터뿐이므로 어댑터가 **표준 낱말**로 말하고(`REFERENCE_STEPS`) 호스트가 자기 두 단계를
- * 더해 이 채널로 흘린다.
- *
- * 낱말이 표준이므로 화면은 **단계마다 번역 하나**만 두면 모든 커넥터를 보여 준다.
- */
-import { Arg, Field, Int, ObjectType, Resolver, Root, Subscription } from 'type-graphql'
-import { assertDomainSubscribeAllowed, getRepository, pubsub } from '@things-factory/shell'
-import { filter, pipe } from 'graphql-yoga'
-
-import { REFERENCE_STEPS } from './reference-progress.js'
-import { REFERENCE_PROGRESS_TOPIC, referenceProgressFilter, type ReferenceProgressPayload } from './reference-progress-channel.js'
-import { TwinReference } from './twin-reference.js'
-
-@ObjectType({ description: 'One step of progress while a reference is being imported into twins.' })
-export class TwinReferenceProgressMessage {
-  @Field({ description: 'Which reference (source) this belongs to.' })
-  source: string
-
-  @Field({ description: 'Which site is being built.' })
-  siteId: string
-
-  @Field({ description: `Standard step name — one of: ${REFERENCE_STEPS.join(' | ')}.` })
-  step: string
-
-  @Field(type => Int, { description: 'Steps finished for this site.' })
-  done: number
-
-  @Field(type => Int, {
-    nullable: true,
-    description: 'Total steps for this site. Absent when the adapter did not declare its steps — the UI then shows no percentage rather than inventing one.'
-  })
-  total?: number
-
-  @Field(type => Int, { description: 'Index of the site being built (0-based).' })
-  siteIndex: number
-
-  @Field(type => Int, { description: 'How many sites are being built.' })
-  siteCount: number
-
-  @Field({ nullable: true, description: 'A fact within the step, such as how many rows were read.' })
-  detail?: string
-
-  @Field({ nullable: true, description: 'True when this step failed. The UI keeps the progress panel and marks this step.' })
-  failed?: boolean
-
-  @Field({ nullable: true, description: 'Why it failed. Present only on failure.' })
-  error?: string
-}
-
-@Resolver()
-export class TwinReferenceProgressSubscription {
-  @Subscription(returns => TwinReferenceProgressMessage, {
-    /*
-     * Tenancy is asked twice (2026-09-24): the source must be one of the caller's references, and every
-     * message must be the caller's domain's. It used to filter on `source` alone after checking only that
-     * the caller had a domain — and source names are shared between tenants.
-     */
-    subscribe: async ({ args, context }) => {
-      const { source } = args
-      const { domain, user } = (context as any)?.state ?? {}
-      await assertDomainSubscribeAllowed(domain, user, (d, u) => process.superUserGranted(d, u))
-      const owned = await getRepository(TwinReference).findOne({ where: { domain: { id: domain.id }, source } })
-      if (!owned) throw new Error(`reference not found in this tenant: ${source}`)
-      return pipe(pubsub.subscribe(REFERENCE_PROGRESS_TOPIC), filter(referenceProgressFilter(domain.id, source)))
-    },
-    description: 'Progress while importing a reference — standard step names, so one translation per step covers every connector.'
-  })
-  twinReferenceProgress(
-    @Root() payload: ReferenceProgressPayload<TwinReferenceProgressMessage>,
-    @Arg('source') source: string
-  ): TwinReferenceProgressMessage {
-    return payload.twinReferenceProgress
-  }
-}

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

@@ -1,95 +0,0 @@
-/*
- * 유입 진행 단계 — **모든 커넥터가 같은 낱말로 말한다.**
- *
- * ── 왜 표준화하나 (2026-08-21) ──────────────────────────────────────────────
- * 마스터 읽기는 원본에 여러 질의를 보내는 긴 작업이고, 그 사이 화면은 아무것도 알 수 없었다. 커넥터마다
- * 자기 낱말로 말하게 두면 화면이 커넥터 수만큼 문구를 알아야 하고, 새 커넥터가 생기면 화면에 낯선 글자가
- * 나온다.
- *
- * 그래서 낱말을 고정한다. 그리고 그 낱말은 **트윈의 자리 이름**이다 — 커넥터가 지금 채우는 자리가 곧
- * 지금 하는 일이다(`design/integration/connector-checklist.md` 의 마스터 축과 같은 이름).
- *
- * 그러면 셋이 함께 얻어진다.
- *  · 화면은 **단계마다 하나의 번역**만 두면 모든 커넥터를 보여 준다.
- *  · 사람은 원본이 달라도 **같은 말로** 진행을 읽는다.
- *  · 실패했을 때 「어느 자리를 읽다 실패했다」가 곧 「트윈의 무엇이 비었다」가 된다.
- *
- * ── 퍼센트를 만들려면 분모가 있어야 한다 ────────────────────────────────────
- * 어댑터가 **자기가 보낼 단계를 미리 선언**한다(`ReferenceAdapter.masterSteps`). 그것이 분모다. 선언하지
- * 않으면 화면은 퍼센트를 보이지 않고 단계 이름만 보인다 — **모르는 진행률을 지어내지 않는다.**
- */
-
-/**
- * 표준 단계. 순서는 대개 이 차례이지만 **강제하지 않는다** — 원본에 따라 없는 자리가 있고, 그때는 그
- * 단계를 선언하지도 보내지도 않는다.
- */
-export const REFERENCE_STEPS = [
-  /** 원본 스키마 확인 — 무엇을 물을 수 있는지 먼저 본다(버전이 다를 수 있다). */
-  'schema',
-  /** 공간·좌표 — 자리가 놓일 좌표계. */
-  'space',
-  /** 자리 — 물건이 놓이고 작업이 일어나는 곳. */
-  'locations',
-  /** 설비 — 일하는 것. */
-  'equipment',
-  /** 공정 — 무슨 일을 하는가. */
-  'operations',
-  /** 자재 — 무엇이 흐르는가. */
-  'materials',
-  /** 경로 — 공정의 순서. */
-  'routes',
-  /** 레시피 — 투입과 산출. */
-  'recipes',
-  /** 시험 명세 — 무엇을 어떻게 검사하는가. */
-  'testSpecifications',
-  /** 인원. */
-  'persons',
-  /** 물리자산. */
-  'assets',
-  /** 트윈 생성 — 여기부터는 호스트가 하는 일이다(어댑터가 선언하지 않는다). */
-  'provision',
-  /** 기동. */
-  'start'
-] as const
-
-export type ReferenceStep = (typeof REFERENCE_STEPS)[number]
-
-/** 호스트가 마스터 읽기 뒤에 하는 단계 — 어댑터의 선언에 이만큼을 더해 분모를 만든다. */
-export const HOST_STEPS: ReferenceStep[] = ['provision', 'start']
-
-/**
- * 한 단계의 진행 — 구독으로 흐르는 메시지의 몸통.
- *
- * `detail` 은 **그 단계 안에서 사람이 알아야 하는 것**이다(읽은 건수 등). 비어 있어도 된다 — 지어내지
- * 않는다.
- */
-export interface ReferenceProgress {
-  /** 어느 사이트를 만드는 중인가. */
-  siteId: string
-  step: ReferenceStep
-  /** 이 사이트에서 끝낸 단계 수. */
-  done: number
-  /** 이 사이트의 전체 단계 수 — 어댑터가 선언하지 않으면 없다(그때 퍼센트를 만들지 않는다). */
-  total?: number
-  /** 여러 사이트를 한 번에 만들 때, 지금 몇 번째인가. */
-  siteIndex: number
-  siteCount: number
-  /** 그 단계 안의 사실 — 「자리 128건」처럼. */
-  detail?: string
-  /** 이 단계에서 실패했는가. 실패해도 화면이 그 자리를 그대로 보여 줄 수 있어야 한다. */
-  failed?: boolean
-  /** 실패 이유 — 실패했을 때만. */
-  error?: string
-}
-
-/**
- * 전체 진행률 — **분모를 알 때만 낸다.**
- *
- * 사이트가 여럿이면 사이트 사이의 진행도 함께 센다: 앞선 사이트는 끝난 것으로 본다.
- */
-export function referencePercent(p: ReferenceProgress): number | undefined {
-  if (!p.total || p.total <= 0 || p.siteCount <= 0) return undefined
-  const perSite = 1 / p.siteCount
-  const within = Math.min(p.done, p.total) / p.total
-  return Math.round((p.siteIndex * perSite + within * perSite) * 100)
-}

package/server/service/reference/reference-reconciliation-query.ts

@@ -1,28 +0,0 @@
-import { Arg, Ctx, Query, Resolver } from 'type-graphql'
-import { getRepository } from '@things-factory/shell'
-import { TwinReferenceReconciliation } from './twin-reference-reconciliation.js'
-
-@Resolver()
-export class TwinReferenceReconciliationQuery {
-  @Query(returns => [TwinReferenceReconciliation], { description: 'All latest durable sequence reconciliations for one Twin. An empty list means no numbered source range has been read yet, not that every source is aligned.' })
-  async twinReferenceReconciliations(
-    @Arg('instanceId') instanceId: string,
-    @Ctx() context: ResolverContext
-  ): Promise<TwinReferenceReconciliation[]> {
-    return getRepository(TwinReferenceReconciliation).find({
-      where: { domain: { id: context.state.domain.id }, instanceId },
-      order: { scope: 'ASC' }
-    })
-  }
-
-  @Query(returns => TwinReferenceReconciliation, { nullable: true, description: 'Latest durable source-range versus Twin-cursor reconciliation for one numbered scope. Null means no backfill has yet obtained a source range; it is not an aligned result.' })
-  async twinReferenceReconciliation(
-    @Arg('instanceId') instanceId: string,
-    @Arg('scope') scope: string,
-    @Ctx() context: ResolverContext
-  ): Promise<TwinReferenceReconciliation | null> {
-    return getRepository(TwinReferenceReconciliation).findOne({
-      where: { domain: { id: context.state.domain.id }, instanceId, scope }
-    })
-  }
-}

package/server/service/reference/reference-reconciliation-writer.ts

@@ -1,38 +0,0 @@
-import { getRepository } from '@things-factory/shell'
-import { TwinReferenceReconciliation } from './twin-reference-reconciliation.js'
-import { reconcileReferenceSequence, type ReferenceRange } from './reference-reconciliation.js'
-
-/** backfill이 원본 범위를 실제로 읽은 뒤에만 최신 대사 상태를 갱신한다. */
-export async function recordReferenceReconciliation(args: {
-  domainId: string
-  instanceId: string
-  scope: string
-  sourceRange?: ReferenceRange
-  cursorSeq?: number
-  firstSeqSeen?: number
-}): Promise<void> {
-  const { domainId, instanceId, scope, sourceRange, cursorSeq, firstSeqSeen } = args
-  if (!sourceRange) return
-  const verdict = reconcileReferenceSequence({ source: sourceRange, cursorSeq, firstSeqSeen })
-  const repo = getRepository(TwinReferenceReconciliation)
-  const previous = await repo.findOne({ where: { domain: { id: domainId }, instanceId, scope } })
-  await repo.save(
-    repo.create({
-      ...(previous ?? {}),
-      domain: { id: domainId } as any,
-      instanceId,
-      scope,
-      status: verdict.status,
-      /* TypeORM은 undefined를 "갱신하지 않음"으로 읽는다. 현재 대사가 맞아진 뒤 옛 gap 수가
-       * 남지 않게 nullable 칸은 명시적으로 null로 지운다. */
-      sourceFirst: verdict.sourceFirst ?? null,
-      sourceLast: verdict.sourceLast ?? null,
-      cursorSeq: verdict.cursorSeq ?? null,
-      firstSeqSeen: verdict.firstSeqSeen ?? null,
-      headMissing: verdict.headMissing ?? null,
-      behind: verdict.behind ?? null,
-      reason: verdict.reason ?? null,
-      checkedAt: new Date()
-    })
-  )
-}

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

@@ -1,55 +0,0 @@
-/*
- * 원본 번호 범위와 Twin 커서를 맞춘 **현재 판정**이다.
- *
- * 이 계산은 봉투 수와 저널 행 수를 비교하지 않는다. 재전송과 backfill 때문에 그 둘은 같은
- * 사실을 여러 번 셀 수 있다. 여기서 답하는 것은 번호를 매기는 원본에서만 가능한, 더 좁고
- * 검증 가능한 질문이다: "원본의 양 끝과 우리가 처음/마지막으로 받은 번호가 이어지는가?"
- */
-export type ReferenceRange = { first?: number; last?: number }
-
-export type ReferenceReconciliation = {
-  sourceFirst?: number
-  sourceLast?: number
-  cursorSeq?: number
-  firstSeqSeen?: number
-  headMissing?: number
-  behind?: number
-  status: 'aligned' | 'gap' | 'unknown'
-  reason?: string
-}
-
-export function reconcileReferenceSequence(args: {
-  source: ReferenceRange | undefined
-  cursorSeq?: number
-  firstSeqSeen?: number
-}): ReferenceReconciliation {
-  const { source, cursorSeq, firstSeqSeen } = args
-  const sourceFirst = source?.first
-  const sourceLast = source?.last
-  const base = { sourceFirst, sourceLast, cursorSeq, firstSeqSeen }
-
-  if (sourceFirst === undefined || sourceLast === undefined) {
-    return { ...base, status: 'unknown', reason: '원본이 번호 범위의 양 끝을 주지 않아 대사할 수 없습니다' }
-  }
-  if (cursorSeq === undefined) {
-    return { ...base, status: 'unknown', reason: 'Twin이 아직 이 단위의 번호를 받은 적이 없습니다' }
-  }
-  if (cursorSeq < sourceFirst) {
-    return {
-      ...base,
-      status: 'unknown',
-      reason: 'Twin 커서가 원본의 첫 번호보다 앞입니다. 원본 번호가 다시 매겨졌거나 다른 단위의 커서입니다'
-    }
-  }
-
-  const behind = Math.max(0, sourceLast - cursorSeq)
-  /* 처음 받은 번호를 적지 않았으면 앞머리는 "없음"이 아니라 "모름"이다. */
-  const headMissing = firstSeqSeen === undefined ? undefined : Math.max(0, firstSeqSeen - sourceFirst)
-  if (behind || headMissing) {
-    return { ...base, ...(behind ? { behind } : {}), ...(headMissing ? { headMissing } : {}), status: 'gap' }
-  }
-  if (firstSeqSeen === undefined) {
-    return { ...base, status: 'unknown', reason: '처음 받은 번호가 기록되지 않아 앞머리 연속성은 확인할 수 없습니다' }
-  }
-  return { ...base, status: 'aligned' }
-}

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

@@ -1,17 +0,0 @@
-/*
- * 레퍼런스 소스 레지스트리 — 호스트에 등록된 레퍼런스 마스터(가상 또는 실 어댑터)를 UI 가 열거·인제스트한다.
- * 앱(operato-twin)이 bootstrap 에서 자기 가상 레퍼런스를 register 하고, 실 배포는 실 시스템 어댑터를 register.
- */
-import type { ReferenceMaster } from './reference-master.js'
-
-const sources = new Map<string, ReferenceMaster>()
-
-export function registerReference(master: ReferenceMaster): void {
-  sources.set(master.source, master)
-}
-export function listReferences(): ReferenceMaster[] {
-  return [...sources.values()]
-}
-export function getReference(source: string): ReferenceMaster | undefined {
-  return sources.get(source)
-}