@things-factory/headless-twin 10.0.8 → 10.0.10

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

@@ -1,12 +1,22 @@
-import { Arg, Ctx, Mutation, Query, Resolver } from 'type-graphql'
+import { Arg, Ctx, Mutation, Query, Resolver, Directive} from 'type-graphql'
 
 import { ScalarObject, getRepository } from '@things-factory/shell'
 
 import { TwinEngine } from '../../engine/index.js'
+import { readBoardEquipment } from '@operato/twin-kernel'
+
+import { applyKnobDefaults, filledKnobKeys } from './knob-defaults.js'
+import type { KnobDef } from './template-registry.js'
+import { knobDefaultsFilled, pickOriginSite, siteEquipmentAdopted } from './reference-master.js'
 import { TwinInstance } from '../twin-instance/twin-instance.js'
 import { TwinReference } from './twin-reference.js'
 import { listReferences, getReference } from './reference-registry.js'
 import { getAdapter, listAdapterTypes, listAdapters } from './reference-adapter.js'
+import {
+  discovered, failed, detailOf,
+  referenceNotFound, adapterUnknown, discoveryFailed, discoveryTimedOut
+} from './discovery-result.js'
+import { refuseImportSpace } from './ingest-space.js'
 import { startReferenceLiveFeed } from './reference-live.js'
 import { listTemplates, getTemplate } from './template-registry.js'
 
@@ -14,6 +24,97 @@ import { listTemplates, getTemplate } from './template-registry.js'
  * Face2 레퍼런스 인제스트 채널(ADR-0018) — 등록된 레퍼런스 소스를 열거하고, 골라서 트윈으로 인제스트.
  * "연결하고 내 것을 불러온다" — 엔티티는 레퍼런스에서 오지 손배선/발명이 아니다.
  */
+
+/**
+ * 발견 조회의 시간 상한 — 15초.
+ *
+ * 어댑터 계약에 시간 제한이 없다. 주소가 틀린 엔드포인트는 답하지 않고, 그러면 화면이 무한히 로딩된다 —
+ * 사용자에게는 "실패" 보다 못한 상태다(무엇을 기다리는지 모른 채 기다린다). 실 시스템 조회가 몇 초
+ * 걸리는 것은 정상이므로 넉넉히 두되, 끝은 있어야 한다.
+ */
+const DISCOVER_TIMEOUT_MS = 15_000
+const TIMEOUT = 'discover-timeout'
+
+function withTimeout<T>(work: Promise<T>, ms: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(Object.assign(new Error('timeout'), { code: TIMEOUT })), ms)
+    work.then(
+      v => { clearTimeout(timer); resolve(v) },
+      e => { clearTimeout(timer); reject(e) }
+    )
+  })
+}
+
+/**
+ * 거절을 **사용자 언어로 옮겨 보낸다** — 번역은 한 곳에서 한다.
+ *
+ * ── 왜 서버인가 (2026-08-14) ────────────────────────────────────────────────
+ * 실측: 실행 중인 트윈을 다시 프로비저닝하면 「instance "order-check" is running — stop before
+ * re-provisioning」 이라는 **영어 한 줄이 토스트로** 떴다(다섯 언어 제품에서).
+ *
+ * 서버와 앱은 **같은 사전**을 쓰고, 사용자의 현재 언어가 백엔드에 반영된다. 그래서 이 문구는 서버가
+ * 옮기는 것이 맞다 — 프레임워크가 이미 같은 규약이다(`authenticate-401-middleware` 가
+ * `context.t('error.' + errorCode, detail)` 로 옮긴다).
+ *
+ * ── 그러면 코드는 왜 함께 보내나 ────────────────────────────────────────────
+ * 화면이 **구조로** 다뤄야 하는 거절이 따로 있다(정합성 표의 행·심각도·수리 버튼 — 그것들은
+ * `twin.compose.chk.*` 처럼 화면이 옮긴다). 그리고 브라우저가 아닌 소비자(AI·스크립트·API)에게는
+ * 코드가 계약이다. 문장과 코드는 서로를 대신하지 않는다.
+ *
+ * **두 곳에서 같은 코드를 옮기지 않는다** — 문장이 두 벌이 되면 반드시 어긋난다.
+ */
+function refusal(context: ResolverContext, e: any, fallback: string): Record<string, unknown> {
+  const code = typeof e?.code === 'string' ? e.code : undefined
+  const params = e?.params && typeof e.params === 'object' ? e.params : undefined
+  /* 영어 canonical 은 항상 남긴다 — 번역 키가 없으면 그것이 보이고, 로그에는 그것이 남는다. */
+  const canonical = e?.message || fallback
+  const message =
+    code && typeof context.t === 'function'
+      ? String(context.t(`twin.provision.err.${code}`, { ...(params ?? {}), defaultValue: canonical }))
+      : canonical
+  return { ok: false, error: message, ...(code ? { errorCode: code } : {}), ...(params ? { errorParams: params } : {}) }
+}
+
+/**
+ * `siteEquipmentIds` 노브를 이 현장의 설비로 채운다 — **비어 있을 때만.**
+ *
+ * 사용자가 목록을 직접 준 경우에는 손대지 않는다(고른 것이 정본이다). 현장이 없으면 채울 것도 없다.
+ * 등록부의 모델에서 읽는다(런타임이 아니다) — 트윈이 도는 중이 아니어도 그 현장의 설비는 사실이다.
+ */
+async function resolveSiteEquipmentKnobs(
+  knobs: readonly KnobDef[] | undefined,
+  effective: Record<string, any>,
+  domainId: string,
+  spaceId?: string
+): Promise<{ key: string; count: number }[]> {
+  const targets = (knobs ?? []).filter(k => k?.type === 'siteEquipment')
+  if (!targets.length) return []
+  const out: { key: string; count: number }[] = []
+  let ids: { id: string; kind: string }[] | undefined
+  for (const k of targets) {
+    const given = effective[k.key]
+    if (Array.isArray(given) && given.length) continue // 사용자가 고른 것이 정본이다
+    if (!spaceId) {
+      effective[k.key] = []
+      continue
+    }
+    if (ids === undefined) {
+      const rows = await getRepository(TwinInstance).find({ where: { domain: { id: domainId }, spaceId } })
+      const seen = new Map<string, { id: string; kind: string }>()
+      for (const r of rows) {
+        for (const e of readBoardEquipment((r.model as any) ?? {})) {
+          if (!e?.id || seen.has(String(e.id))) continue
+          seen.set(String(e.id), { id: String(e.id), kind: String((e as any).kind ?? '') })
+        }
+      }
+      ids = [...seen.values()]
+    }
+    effective[k.key] = ids
+    out.push({ key: k.key, count: ids.length })
+  }
+  return out
+}
+
 @Resolver()
 export class TwinReferenceResolver {
   /** 등록된 레퍼런스 소스 목록(요약 + 이미 인제스트됐는지). */
@@ -31,13 +132,14 @@ export class TwinReferenceResolver {
         areaCount: m.locations.filter(l => l.role === 'area' || l.role === 'both').length,
         equipmentCount: (m.equipment ?? []).length,
         imported: !!reg,
-        running: !!TwinEngine.instances[m.source]
+        running: TwinEngine.owns(domainId, m.source)
       })
     }
     return out
   }
 
   /** 소스를 인제스트 → 공간 + 인스턴스 생성(provision). start 면 기동까지. */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => ScalarObject, { description: 'Ingest a registered reference source into a twin (space + instance). Optionally start it.' })
   async importFromReference(
     @Arg('source') source: string,
@@ -48,14 +150,121 @@ export class TwinReferenceResolver {
     if (!master) return { ok: false, error: `unknown reference source: ${source}` }
     const domainId = context.state.domain.id
     try {
-      const res = await TwinEngine.ingestMaster(domainId, master)
+      /* 어디서 왔는지 남긴다 — 이것이 없으면 이 트윈은 두 번 다시 읽을 수 없다.
+         이 경로는 **메모리에 등록된 마스터 하나**를 그대로 쓰므로 사이트 서술자가 없다(사이트 정체를
+         적을 것이 없다). 다시 읽기도 같은 등록본을 집으므로 사이트를 찾을 필요가 없다. */
+      const res = await TwinEngine.ingestMaster(domainId, { ...master, origin: { kind: 'reference', source } }, undefined, context.state.user)
       if (start) await TwinEngine.startFromRegistry(domainId, res.instanceId)
       return { ok: true, instanceId: res.instanceId, spaceId: res.spaceId, warnings: res.warnings }
     } catch (e: any) {
-      return { ok: false, error: e?.message || 'ingest failed' }
+      return refusal(context, e, 'ingest failed')
     }
   }
 
+  /**
+   * **원본에서 다시 읽는다** — 이 트윈의 구조를 지금의 원본 모습으로 갱신한다.
+   *
+   * ── 왜 진입점이 하나여야 하나 ──────────────────────────────────────────────
+   * 지금까지 다시 읽기는 **만드는 경로에 얹혀 있었다**(`importFromReference`·`createFromTemplate`).
+   * 그래서 이미 있는 트윈을 갱신하려면 만들 때 무엇을 골랐는지 사람이 기억해 같은 화면을 다시
+   * 거쳐야 했고, 템플릿으로 세운 트윈은 노브를 어디에도 안 남겨서 **아예 갱신할 방법이 없었다.**
+   * 원천이 무엇이든 트윈 자신이 기억하게 하고(`TwinInstance.origin`), 여기 한 곳에서 그것을 따른다.
+   *
+   * ── 무엇이 일어나나 ────────────────────────────────────────────────────────
+   * 원본에서 마스터를 다시 얻어 인제스트에 그대로 태운다. 그다음은 인제스트가 아는 일이다 —
+   * 구조가 달라졌으면 새 리비전이 남고, 구조 행이 다시 그려지고, **실행 중인 미러는 멈추지 않고
+   * 전환한다.** 실행 중인 시뮬레이션은 거절된다(조건이 바뀐 실험은 다른 실험이다).
+   *
+   * ── 못 할 때는 못 한다고 한다 ──────────────────────────────────────────────
+   * `origin` 이 없는 트윈(이 자리가 생기기 전에 만들어진 것)은 다시 읽을 수 없다. 짐작으로
+   * 템플릿을 고르거나 첫 레퍼런스를 집지 않는다 — 엉뚱한 원본으로 현장을 덮는 것이 훨씬 나쁘다.
+   */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Mutation(returns => ScalarObject, {
+    description:
+      "Re-read a twin's structure from the source it remembers (TwinInstance.origin). Works for both reference- and template-born twins. A running mirror adopts the new structure without stopping; a running simulation is refused."
+  })
+  async resyncTwin(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<any> {
+    const domainId = context.state.domain.id
+    const inst = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })
+    if (!inst) return { ok: false, error: `unknown twin: ${instanceId}` }
+
+    const origin = inst.origin as any
+    if (!origin?.kind)
+      return {
+        ok: false,
+        error: `twin "${instanceId}" does not remember where it came from — it cannot be re-read. Re-create it from its template or reference so the origin is recorded.`
+      }
+
+    try {
+      const master = await this.masterFromOrigin(domainId, origin, instanceId)
+      /*
+       * **어느 현장의 트윈이었나를 지킨다** — 다시 읽기는 구조만 새로 그리는 일이고, 현장 소속은 그때
+       * 사람이 고른 것이다. 기억이 없는 옛 트윈은 **지금 있는 현장**을 그대로 쓴다(빈손으로 두면 템플릿
+       * 기본 공간으로 옮겨 간다 — 조용히 현장을 떠나고 그 현장의 값도 잃는다).
+       */
+      const keepSpace = origin.spaceId || inst.spaceId
+      const res = await TwinEngine.ingestMaster(domainId, master, keepSpace ? { spaceId: keepSpace } : undefined, context.state.user)
+      return { ok: true, instanceId: res.instanceId, spaceId: res.spaceId, warnings: res.warnings }
+    } catch (e: any) {
+      return refusal(context, e, 'resync failed')
+    }
+  }
+
+  /** 기억해 둔 원천에서 마스터를 다시 얻는다 — 어댑터든 템플릿이든 이 한 곳에서 갈린다. */
+  private async masterFromOrigin(domainId: string, origin: any, instanceId: string): Promise<any> {
+    if (origin.kind === 'template') {
+      const tpl = getTemplate(origin.templateId)
+      if (!tpl) throw new Error(`unknown template: ${origin.templateId} — this twin cannot be rebuilt`)
+      /* 저장해 둔 노브 그대로 다시 짓는다. 기본값을 다시 입히지 않는다 — 그 사이 템플릿의 기본값이
+         바뀌었다면, 사용자가 고르지 않은 값이 조용히 현장을 바꾸게 된다. */
+      const { master } = tpl.build(origin.params ?? {})
+      master.origin = origin
+      return master
+    }
+
+    /* 레퍼런스 — 메모리 등록본이 있으면 그것, 없으면 저장된 어댑터 연결로 다시 가져온다.
+       (부팅 뒤에는 메모리 등록본이 비어 있으므로 어댑터 경로가 실제로 쓰이는 길이다.) */
+    const inMemory = getReference(origin.source)
+    if (inMemory) return { ...inMemory, origin }
+
+    const ref = await getRepository(TwinReference).findOne({ where: { domain: { id: domainId }, source: origin.source } })
+    if (!ref) throw new Error(`reference "${origin.source}" is no longer registered — nothing to re-read from`)
+    const adapter = getAdapter(ref.adapterType)
+    if (!adapter) throw new Error(`no adapter for type: ${ref.adapterType}`)
+    const cfg = ref.connectionConfig ?? {}
+    const sites = await adapter.discoverSites(cfg)
+
+    /*
+     * ── 무엇을 무엇과 견주나 (2026-08-18 실측으로 고침) ────────────────────────
+     *
+     * 예전에는 `master.source === origin.source` 로 사이트를 찾았다. 그런데 `origin.source` 는 **레퍼런스
+     * 등록 이름**이고(그 참조의 사이트 전부에 같다) `master.source` 는 **사이트별 인스턴스 id** 다 —
+     * 서로 다른 것을 견줬으니 사이트가 멀쩡히 있어도 「더 이상 보고하지 않는다」로 거절했다. 사이트가
+     * 여럿인 참조에서 온 트윈은 그래서 **전부** 재동기가 불가했고, 오류 문장은 원인을 참조 쪽으로
+     * 잘못 가리켰다.
+     *
+     * 이제 ① 기억해 둔 사이트로 곧장 간다(`origin.siteId`) ② 기억이 없는 옛 트윈은 사이트를 살펴
+     * **마스터의 정체(=이 인스턴스 id)** 와 견준다. 어느 쪽도 못 찾으면 **첫 사이트로 때우지 않는다** —
+     * 다른 현장의 구조를 이 트윈에 덮는 것은 오류가 아니라 조용히 틀린 공장으로 나타난다.
+     */
+    const picked = pickOriginSite(sites, origin)
+    if (picked.site) return { ...(await adapter.fetchMaster(cfg, picked.site)), origin }
+    if (picked.reason === 'site-gone')
+      throw new Error(
+        `reference "${origin.source}" no longer reports site "${origin.siteId}" — refusing to overwrite this twin with a different site`
+      )
+
+    for (const site of sites) {
+      const master = await adapter.fetchMaster(cfg, site)
+      if (master.source === instanceId) return { ...master, origin: { ...origin, siteId: site.siteId } }
+    }
+    throw new Error(
+      `reference "${origin.source}" does not report a site that rebuilds twin "${instanceId}" ` +
+        `(this twin was imported before the site identity was recorded, and no site's master carries its id) — refusing to overwrite it with a different site`
+    )
+  }
+
   /** 등록된 트윈 템플릿(파라미터화 아키타입) 목록 — 노브 스키마 포함(클라이언트 폼용). */
   @Query(returns => [ScalarObject], { description: 'List registered twin templates (parameterized archetypes) with their knob schema.' })
   async twinTemplates(@Ctx() _context: ResolverContext): Promise<any[]> {
@@ -63,32 +272,63 @@ export class TwinReferenceResolver {
   }
 
   /** 템플릿 + 노브 → 합성 마스터 → 인제스트(+기동+시나리오). 레퍼런스 import 와 같은 경로, 원천만 합성. */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => ScalarObject, { description: 'Instantiate a twin template with params → synthetic master → ingest (+start+scenario). Returns {ok, instanceId, spaceId}.' })
   async createFromTemplate(
     @Arg('templateId') templateId: string,
     @Arg('params', type => ScalarObject) params: any,
     @Ctx() context: ResolverContext,
-    @Arg('start', { nullable: true }) start?: boolean
+    @Arg('start', { nullable: true }) start?: boolean,
+    @Arg('spaceId', { nullable: true, description: 'Existing space to co-locate this twin into (add a lens to a site). Omit to create its own space.' }) spaceId?: string
   ): Promise<any> {
     const tpl = getTemplate(templateId)
     if (!tpl) return { ok: false, error: `unknown template: ${templateId}` }
     const domainId = context.state.domain.id
     try {
-      const { master, scenario } = tpl.build(params || {})
-      const res = await TwinEngine.ingestMaster(domainId, master)
+      /*
+       * **빠진 노브를 서버가 채운다.** 기본값을 아는 곳은 노브 스키마(계약)인데 그것을 적용하는 곳이
+       * 위자드뿐이었다 — 그래서 화면을 거치지 않는 호출자(AI·스크립트·API)가 파라미터를 일부만 주면
+       * 템플릿 안에서 발생률이 0 이 되고 **아무것도 하지 않는 트윈**이 조용히 만들어졌다.
+       * 채운 노브 이름은 경고로 함께 돌려준다 — 조용히 채우는 것도 조용히 비우는 것만큼 위험하다.
+       */
+      const filled = filledKnobKeys(tpl.knobs, params)
+      const effective = applyKnobDefaults(tpl.knobs, params)
+      /*
+       * **이 현장에 이미 있는 설비를 노브 값으로 확정한다** (`siteEquipmentIds`).
+       *
+       * 에너지 트윈이 「공장이 돌면 전기가 오른다」를 말하려면 부하를 **이웃 트윈의 설비 id 로**
+       * 선언해야 한다(설비 하나에 사실 둘). 그 목록을 빌드할 때마다 현장에서 다시 읽으면, 사이에
+       * 설비가 늘거나 준 만큼 **다시 지을 때 다른 트윈**이 된다. 그래서 여기서 한 번 해석하고
+       * 그 결과를 노브 값으로 남긴다(아래 `origin.params` 에 그대로 저장된다).
+       */
+      const adopted = await resolveSiteEquipmentKnobs(tpl.knobs, effective, domainId, spaceId)
+      const { master, scenario } = tpl.build(effective)
+      /* **무엇으로 지었는지 남긴다.** 합성은 결정적이므로 같은 노브면 같은 마스터가 다시 나온다 —
+         그래서 템플릿 트윈도 어댑터 트윈과 똑같이 다시 읽을 수 있다. 남기지 않으면 그 트윈은
+         첫날의 모습에 영원히 머문다(원본을 잃은 트윈). */
+      /* 고른 현장도 남긴다 — 없으면 다시 읽기가 트윈을 템플릿 기본 공간으로 옮겨 버린다(현장 값도 잃는다). */
+      master.origin = { kind: 'template', templateId, params: effective, ...(spaceId ? { spaceId } : {}) }
+      /* 공간 선택은 템플릿을 거치지 않는다 — 템플릿마다 이 노브를 알고 있어야 한다면 새 템플릿이
+         조용히 무시하게 된다. 합성된 마스터에 한 곳에서 얹는다(레퍼런스 인제스트와 같은 경로). */
+      const res = await TwinEngine.ingestMaster(domainId, master, { spaceId }, context.state.user)
       if (start !== false) {
         await TwinEngine.startFromRegistry(domainId, res.instanceId)
         if (scenario) {
-          const runtime = TwinEngine.runtime(res.instanceId)
+          const runtime = TwinEngine.runtime(domainId, res.instanceId)
           if (runtime) {
             runtime.scenario.load(scenario)
             runtime.scenario.start()
           }
         }
       }
-      return { ok: true, instanceId: res.instanceId, spaceId: res.spaceId, warnings: res.warnings }
+      const warnings = [
+        ...(filled.length ? [knobDefaultsFilled(filled)] : []),
+        ...adopted.filter(a => a.count > 0).map(a => siteEquipmentAdopted(a.key, a.count)),
+        ...res.warnings
+      ]
+      return { ok: true, instanceId: res.instanceId, spaceId: res.spaceId, warnings }
     } catch (e: any) {
-      return { ok: false, error: e?.message || 'template instantiation failed' }
+      return refusal(context, e, 'template instantiation failed')
     }
   }
 
@@ -155,7 +395,7 @@ export class TwinReferenceResolver {
       .filter(p => instMap.has(p.instanceId))
       .map(p => {
         const inst = instMap.get(p.instanceId) as any
-        return { instanceId: p.instanceId, spaceId: p.spaceId, siteId: p.siteId, kind: inst.kind, status: inst.status, running: !!(TwinEngine as any).instances?.[p.instanceId] }
+        return { instanceId: p.instanceId, spaceId: p.spaceId, siteId: p.siteId, kind: inst.kind, status: inst.status, running: TwinEngine.owns(domainId, p.instanceId) }
       })
     return {
       source: r.source,
@@ -188,6 +428,7 @@ export class TwinReferenceResolver {
     return listAdapters().map(a => ({ type: a.type, ...(a.meta ?? {}) }))
   }
 
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => ScalarObject, { description: 'Create or update a tenant-scoped twin reference (persisted).' })
   async saveTwinReference(
     @Arg('source') source: string,
@@ -219,6 +460,7 @@ export class TwinReferenceResolver {
   }
 
   /** 연결 해제 — removeTwins=true 면 이 레퍼런스가 만든 트윈(provenance)도 함께 제거(라이프사이클 연쇄). 기본은 트윈 보존(분리). */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, { description: 'Delete a tenant-scoped reference. If removeTwins, also remove the twin instances it produced (provenance cascade); otherwise twins are kept (detached).' })
   async deleteTwinReference(
     @Arg('source') source: string,
@@ -241,6 +483,7 @@ export class TwinReferenceResolver {
     return true
   }
 
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => ScalarObject, { description: 'Test a reference connection via its adapter; updates status.' })
   async testReferenceConnection(@Arg('source') source: string, @Ctx() context: ResolverContext): Promise<any> {
     const repo = getRepository(TwinReference)
@@ -262,30 +505,54 @@ export class TwinReferenceResolver {
    * P1 은 대개 N=1(virtual/단일). start 면 각 인스턴스 기동. 라이브 피드·mode 는 face2-inbound-live 소유.
    */
   /** 레퍼런스가 노출하는 사이트/공장 발견 — 트윈 생성 시 "어느 공장" 선택용(§2.2). */
-  @Query(returns => [ScalarObject], { description: 'Discover sites/factories exposed by a reference (adapter.discoverSites) — for twin-creation site selection.' })
-  async discoverReferenceSites(@Arg('source') source: string, @Ctx() context: ResolverContext): Promise<any[]> {
+  @Query(returns => ScalarObject, { description: 'Discover sites/factories exposed by a reference. Returns { sites, error? } — an empty list with no error means the system genuinely has none, which is different from a failure.' })
+  async discoverReferenceSites(@Arg('source') source: string, @Ctx() context: ResolverContext): Promise<any> {
+    /*
+     * **"못 찾았다" 와 "없다" 를 구분한다.** 예전에는 넷을 빈 배열 하나로 접었고(레퍼런스 없음·어댑터
+     * 미상·조회 실패·정말 0건), 화면은 그 모두를 "사이트를 찾지 못했습니다" 라고만 말했다. 실 시스템
+     * 연결에서 가장 자주 막히는 자리인데 자격이 틀렸는지 주소가 틀렸는지 알 수 없었다.
+     * 판정과 문장 형태는 `discovery-result`(순수)가 갖는다.
+     */
     const ref = await getRepository(TwinReference).findOne({ where: { domain: { id: context.state.domain.id }, source } })
-    if (!ref) return []
+    if (!ref) return failed(referenceNotFound(source))
     const adapter = getAdapter(ref.adapterType)
-    if (!adapter) return []
+    if (!adapter) return failed(adapterUnknown(ref.adapterType, source))
     try {
-      return await adapter.discoverSites(ref.connectionConfig ?? {})
-    } catch {
-      return []
+      /*
+       * **기다려도 답이 없으면 사유를 준다.** 어댑터 계약에 시간 제한이 없어서, 주소가 틀린 엔드포인트는
+       * 화면을 무한히 돌게 만들었다 — 무한히 도는 화면은 조용한 실패의 다른 얼굴이다.
+       * 상한은 여기서 정한다(어댑터마다 다르게 두면 사용자가 어느 것을 기다리는지 알 수 없다).
+       */
+      const sites = await withTimeout(adapter.discoverSites(ref.connectionConfig ?? {}), DISCOVER_TIMEOUT_MS)
+      return discovered(sites)
+    } catch (e: any) {
+      if (e?.code === TIMEOUT) return failed(discoveryTimedOut(source, DISCOVER_TIMEOUT_MS / 1000))
+      return failed(discoveryFailed(source, detailOf(e)))
     }
   }
 
   /**
    * 트윈 생성 — 레퍼런스에서 사이트 발견 → (siteIds 있으면 그 공장만) → fetchMaster → provision. 사이트별 resilient.
    * 여러 공장을 관할하는 소스는 siteIds 로 "어느 공장"을 골라 생성(1:N, §2.1·§2.2).
+   *
+   * ── 현장 선택이 이 경로에도 있다 (2026-08-13) ────────────────────────────
+   * 한 현실을 여러 렌즈가 비춘다(WMS·MES·YMS). 그런데 **그 선택이 템플릿 경로에만** 있어서
+   * (`createFromTemplate(spaceId)`), 실 시스템에서 가져온 트윈은 어댑터가 파생한 공간 id 가 우연히
+   * 일치할 때만 한 현장에 모였다 — 사람이 "이 MES 와 같은 현장에 넣어라" 를 말할 방법이 없었다.
+   * 데이터로는 가능한 일이 저작으로는 불가능한, `ingest-space` 가 이미 지적한 그 비대칭이다.
+   *
+   * 판정은 그 순수 모듈이 갖는다: 없는 공간은 거절(`resolveIngestSpace`), 사이트 여럿을 한 공간에
+   * 넣는 것도 거절(`refuseImportSpace`) — 서로 다른 현장이 조용히 합쳐지는 것을 막는다.
    */
-  @Mutation(returns => ScalarObject, { description: 'Create twins from a reference: discover sites → filter by siteIds (if given) → fetch master(s) → provision. start=false to only provision; live=true to run as a mirror (adapter openLiveFeed → live projector) instead of sim.' })
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Mutation(returns => ScalarObject, { description: 'Create twins from a reference: discover sites → filter by siteIds (if given) → fetch master(s) → provision. spaceId co-locates the twin into an existing space (one site only). start=false to only provision; live=true to run as a mirror (adapter openLiveFeed → live projector) instead of sim.' })
   async importTwinReference(
     @Arg('source') source: string,
     @Ctx() context: ResolverContext,
     @Arg('siteIds', type => [String], { nullable: true }) siteIds?: string[],
     @Arg('start', { nullable: true }) start?: boolean,
-    @Arg('live', { nullable: true }) live?: boolean
+    @Arg('live', { nullable: true }) live?: boolean,
+    @Arg('spaceId', { nullable: true, description: 'Existing space to co-locate this twin into (add a lens to a site). Only when importing a single site. Omit to give each site its own space.' }) spaceId?: string
   ): Promise<any> {
     const domainId = context.state.domain.id
     const repo = getRepository(TwinReference)
@@ -297,12 +564,22 @@ export class TwinReferenceResolver {
     try {
       let sites = await adapter.discoverSites(cfg)
       if (siteIds?.length) sites = sites.filter(s => siteIds.includes(s.siteId))
+      /* 아무것도 쓰기 전에 거절한다 — 한 사이트를 넘으면 "이 현장에 더한다" 가 성립하지 않는다. */
+      const refusal = refuseImportSpace(sites.length, spaceId)
+      if (refusal) return { ok: false, error: refusal.message, errorCode: refusal.code, errorParams: refusal.params }
       const instances: any[] = []
       const failed: any[] = []
       for (const site of sites) {
         try {
           const master = await adapter.fetchMaster(cfg, site)
-          const res = await TwinEngine.ingestMaster(domainId, master)
+          /* 어느 레퍼런스의 **어느 사이트**에서 왔는지 남긴다 — 다시 읽기가 같은 어댑터·같은 사이트로 돌아오려면
+             사이트 정체가 있어야 한다(`source` 는 참조 이름이라 사이트 전부에 같다). */
+          const res = await TwinEngine.ingestMaster(
+            domainId,
+            { ...master, origin: { kind: 'reference', source, siteId: site.siteId, ...(spaceId ? { spaceId } : {}) } },
+            { spaceId },
+            context.state.user
+          )
           if (start !== false) {
             // live=true + 어댑터가 openLiveFeed 지원 → mirror(실 이벤트 미러). 아니면 sim 기동(fallback).
             const wentLive = live ? await startReferenceLiveFeed(domainId, ref.adapterType, cfg, site, res.instanceId) : false
@@ -323,14 +600,21 @@ export class TwinReferenceResolver {
         {
           status: 'connected',
           lastSyncedAt: new Date().toISOString(),
-          lastError: failed.length ? `${failed.length}개 사이트 실패` : null,
+          /*
+           * **영어 canonical 로 남긴다.** 이 값은 DB 에 저장되고 연결 화면이 그대로 뿌린다 — 예전에는
+           * 한글 산문(`N개 사이트 실패`)이라 다섯 언어 화면에 한글이 새어 나갔다. 어댑터가 주는 사유도
+           * 같은 필드에 들어오므로(그것은 원 시스템의 말이다) 키가 아니라 영어 문장으로 통일한다.
+           * 어느 사이트가 왜 실패했는지는 `failed[]` 가 답한다 — 화면이 그것을 보여 준다.
+           */
+          lastError: failed.length ? `${failed.length} of ${sites.length} site(s) failed: ${failed.map((f: any) => f.siteId).join(', ')}` : null,
           scopeSpec: { ...((ref.scopeSpec as any) ?? {}), produced: [...prev, ...producedNew] }
         } as any
       )
       return { ok: instances.length > 0, instances, failed }
     } catch (e: any) {
+      /* 레퍼런스 행에는 **영어 canonical** 을 남긴다 — 저장되는 값은 언어중립이어야 다시 읽을 수 있다. */
       await repo.update({ id: ref.id }, { status: 'error', lastError: e?.message ?? 'ingest failed' } as any)
-      return { ok: false, error: e?.message ?? 'ingest failed' }
+      return refusal(context, e, 'ingest failed')
     }
   }
 }

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

@@ -2,8 +2,10 @@
  * 트윈 템플릿(아키타입) 레지스트리 — 파라미터화된 합성 레퍼런스 마스터 빌더.
  * 레퍼런스(reference-registry)가 "고정 마스터"라면, 템플릿은 "노브로 파라미터화된 마스터 빌더".
  * 둘 다 같은 인제스트 경로(ingestMaster)로 흐른다 — 원천이 고정이냐 합성이냐만 다르다(board-authoring §10).
- * 앱(operato-twin)이 bootstrap 에서 자기 아키타입을 registerTemplate 한다. 표현(map/image/board) 무관.
+ * 앱(operato-twin)이 bootstrap 에서 자기 아키타입을 registerTemplate 한다. 표현(map/image/model) 무관.
  */
+import type { DomainSystem } from '@operato/twin-kernel'
+
 import type { ReferenceMaster } from './reference-master.js'
 
 /** 사용자 노출 파라미터(노브) 정의 — 클라이언트가 이 스키마로 폼을 렌더한다. */
@@ -11,7 +13,14 @@ export interface KnobDef {
   key: string
   /** 'geo' = 위경도 지점(지도에서 클릭 선택). 값은 { lat, lon }. 사용자가 좌표를 몰라도 지도로 지정. */
   label: string
-  type: 'number' | 'text' | 'select' | 'geo'
+  /**
+   * 'siteEquipment' = **이 현장에 이미 있는 설비들**(`{id, kind}`). 값이 비어 있으면 만들 때 한 번
+   * 해석해서 채우고, 채운 결과를 노브 값으로 **남긴다**(`origin.params`). 그래야 나중에 다시 지어도
+   * 같은 트윈이 나온다 — 그때그때 현장을 다시 읽으면 사이에 설비가 늘고 준 만큼 다른 트윈이 된다.
+   *
+   * 종류를 함께 싣는 이유: 무엇을 받아들일지는 **템플릿이 종류로 판단**한다(이름으로 짐작하지 않는다).
+   */
+  type: 'number' | 'text' | 'select' | 'geo' | 'siteEquipment'
   default: any
   min?: number
   max?: number
@@ -40,8 +49,13 @@ export interface TemplateDetail {
     /** 완성 라우트 이름(공정 라우트 참조). */
     route?: string
   }
-  /** 표준 정합 매핑(개념 ↔ EPCIS/ISA-95). */
-  standardsMap?: { concept: string; epcis?: string; isa95?: string }[]
+  /**
+   * 표준 정합 매핑 — 개념이 **어느 표준의 무엇에 대응하나.**
+   *
+   * 표준 칸이 EPCIS·ISA-95 둘로 굳어 있었다. 에너지 템플릿은 그 둘이 앵커가 아니라 적을 자리가 없었다 —
+   * 커널의 `StandardClass` 도 같은 이유로 열었다(`iso50001`·`iec61850`). 대응할 이름이 없으면 **비운다**.
+   */
+  standardsMap?: { concept: string; epcis?: string; isa95?: string; iso50001?: string; iec61850?: string }[]
   /** "이 템플릿이 맞나?" 판단 도움 항목. */
   fits?: string[]
 }
@@ -49,7 +63,8 @@ export interface TemplateDetail {
 export interface TwinTemplate {
   id: string
   label: string
-  system: 'wms' | 'yms' | 'mes'
+  /** 커널 카탈로그가 정본 — 종류가 늘면 여기 손댈 것이 없다(`DomainSystem`). */
+  system: DomainSystem
   description?: string
   /** 상세 설명(선택) — 설명 페이지/패널이 렌더. */
   detail?: TemplateDetail

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

@@ -1,8 +1,9 @@
-import { Arg, Ctx, Query, Resolver } from 'type-graphql'
+import { Arg, Ctx, Int, Query, Resolver } from 'type-graphql'
 
 import { ScalarObject } from '@things-factory/shell'
 
 import { TwinEngine } from '../../engine/index.js'
+import { digestAttentions } from '../../engine/attention-digest.js'
 
 /*
  * 주목 신호(Attention) 질의 — 현재 스냅샷의 요약된 "봐야 할 것".
@@ -16,11 +17,47 @@ export class TwinAttentionQuery {
   @Query(returns => [ScalarObject], {
     description: 'Active attention signals (things to look at) derived from the current twin snapshot — severity (ISA-18.2), lifecycle state (OPC UA A&C), space anchor, and suggested action.'
   })
-  async twinAttentions(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<any[]> {
-    if (!TwinEngine.owns(context.state.domain.id, instanceId)) return [] // 테넌트 격리
+  async twinAttentions(
+    @Ctx() context: ResolverContext,
+    @Arg('instanceId', { nullable: true }) instanceId?: string,
+    /*
+     * **공간으로 물으면 그 현장의 모든 렌즈에서 모아 답한다** — 한 현실을 WMS·MES·YMS 가 함께 비추므로
+     * "이 현장에서 봐야 할 것" 은 렌즈 하나로 답할 수 없다. 예전에는 화면이 인스턴스마다 물어 손으로
+     * 합쳤고, 그러면 정렬 규칙이 화면마다 갈린다.
+     *
+     * 경고는 **합집합이 그대로 뜻이 있는 유일한 렌즈**다. 예측은 합칠 수 없다(P50 두 개를 더할 수 없다) —
+     * 그래서 예측은 여전히 인스턴스별로 답하고 화면이 나란히 놓는다.
+     */
+    @Arg('spaceId', { nullable: true }) spaceId?: string,
+    /** 상위 몇 건만 — 말하지 않으면 자르지 않는다. 전체 개수는 `twinAttentionDigest` 가 함께 답한다. */
+    @Arg('limit', type => Int, { nullable: true }) limit?: number
+  ): Promise<any[]> {
+    if (spaceId) return (await TwinEngine.attentionsOfSpace(context.state.domain.id, spaceId, limit ?? undefined)).attentions
+    if (!instanceId || !TwinEngine.owns(context.state.domain.id, instanceId)) return [] // 테넌트 격리
     // 라이브 커널 스냅샷(fresh) 우선 — snapshot()=resync() 는 캐시라 커맨드 델타 지연(recover 와 동일 원천 사용).
-    const kernel = TwinEngine.kernel(instanceId)
-    const snap = kernel?.getSnapshot?.() ?? TwinEngine.snapshot(instanceId)
-    return snap?.attentions ?? []
+    const kernel = TwinEngine.kernel(context.state.domain.id, instanceId)
+    const snap = kernel?.getSnapshot?.() ?? TwinEngine.snapshot(context.state.domain.id, instanceId)
+    const list = snap?.attentions ?? []
+    return limit && limit > 0 ? digestAttentions(list, limit).attentions : list
+  }
+
+  /**
+   * 잘랐다면 **몇 건을 잘랐는지**와 자리 색 요약까지 — 목록만 주면 화면이 "N건 더" 를 말할 수 없다.
+   * 자리별 최고 심각도는 **전량을 근거로** 접는다(상위 N 으로 접으면 20위 밖 신호를 가진 자리가 색을 잃는다).
+   */
+  @Query(returns => ScalarObject, {
+    description: 'Attention signals for a space (all its lenses) or one twin, with the total count and the per-location highest severity folded from all of them.'
+  })
+  async twinAttentionDigest(
+    @Ctx() context: ResolverContext,
+    @Arg('spaceId', { nullable: true }) spaceId?: string,
+    @Arg('instanceId', { nullable: true }) instanceId?: string,
+    @Arg('limit', type => Int, { nullable: true }) limit?: number
+  ): Promise<any> {
+    if (spaceId) return TwinEngine.attentionsOfSpace(context.state.domain.id, spaceId, limit ?? undefined)
+    if (!instanceId || !TwinEngine.owns(context.state.domain.id, instanceId)) return { attentions: [], attentionTotal: 0, severityByLocation: {} }
+    const kernel = TwinEngine.kernel(context.state.domain.id, instanceId)
+    const snap = kernel?.getSnapshot?.() ?? TwinEngine.snapshot(context.state.domain.id, instanceId)
+    return digestAttentions((snap?.attentions ?? []).map((a: any) => ({ ...a, instanceId })), limit ?? undefined)
   }
 }