@things-factory/headless-twin 10.0.8 → 10.0.9

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

@@ -1,12 +1,18 @@
-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 { applyKnobDefaults, filledKnobKeys } from './knob-defaults.js'
+import { knobDefaultsFilled } 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 { startReferenceLiveFeed } from './reference-live.js'
 import { listTemplates, getTemplate } from './template-registry.js'
 
@@ -14,6 +20,27 @@ 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) }
+    )
+  })
+}
+
 @Resolver()
 export class TwinReferenceResolver {
   /** 등록된 레퍼런스 소스 목록(요약 + 이미 인제스트됐는지). */
@@ -31,13 +58,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,
@@ -63,30 +91,43 @@ 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)
+      const { master, scenario } = tpl.build(effective)
+      /* 공간 선택은 템플릿을 거치지 않는다 — 템플릿마다 이 노브를 알고 있어야 한다면 새 템플릿이
+         조용히 무시하게 된다. 합성된 마스터에 한 곳에서 얹는다(레퍼런스 인제스트와 같은 경로). */
+      const res = await TwinEngine.ingestMaster(domainId, master, { spaceId })
       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), ...res.warnings] : res.warnings
+      return { ok: true, instanceId: res.instanceId, spaceId: res.spaceId, warnings }
     } catch (e: any) {
       return { ok: false, error: e?.message || 'template instantiation failed' }
     }
@@ -155,7 +196,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 +229,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 +261,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 +284,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,16 +306,29 @@ 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)))
     }
   }
 
@@ -279,6 +336,7 @@ export class TwinReferenceResolver {
    * 트윈 생성 — 레퍼런스에서 사이트 발견 → (siteIds 있으면 그 공장만) → fetchMaster → provision. 사이트별 resilient.
    * 여러 공장을 관할하는 소스는 siteIds 로 "어느 공장"을 골라 생성(1:N, §2.1·§2.2).
    */
+  @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. 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,
@@ -323,7 +381,13 @@ 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
       )

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

package/server/service/twin-control/twin-control-mutation.ts

@@ -1,4 +1,6 @@
-import { Arg, Ctx, Mutation, Resolver } from 'type-graphql'
+import { Arg, Ctx, Mutation, Resolver, Directive} from 'type-graphql'
+
+import { validateScenario } from '@operato/twin-kernel'
 
 import { ScalarObject } from '@things-factory/shell'
 
@@ -15,27 +17,31 @@ import { TwinEngine } from '../../engine/index.js'
 @Resolver()
 export class TwinControlMutation {
   /** Command 채널 — 오더 hold/resume/release 등. 커널 dispatch 로 위임, ack{accepted,error} 반환. */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => ScalarObject, { description: 'dispatch a twin command (order.hold/resume/release …). Returns {accepted, error?}.' })
   async dispatchTwinCommand(
     @Arg('instanceId') instanceId: string,
     @Arg('command', type => ScalarObject) command: any,
     @Ctx() context: ResolverContext
-  ): Promise<{ accepted: boolean; error?: string }> {
+  ): Promise<{ accepted: boolean; error?: string; errorCode?: string; errorParams?: Record<string, string | number> }> {
     const domainId = context.state.domain?.id
-    const inst = TwinEngine.instances[instanceId]
-    if (!inst || inst.domainId !== domainId) {
-      return { accepted: false, error: 'instance not found in your domain' }
-    }
-    /* tenantId 를 호출자 도메인으로 각인(감사·무결성) — 클라 위조 방지. */
-    const ack = inst.runtime.dispatch({ ...command, tenantId: domainId })
+    if (!domainId) return { accepted: false, error: 'no-domain', errorCode: 'no-domain' }
+    /*
+     * 라우팅은 엔진이 한다 — 예전에는 여기서 `inst.runtime.dispatch` 를 곧바로 불렀고, `runtime` 이
+     * 시뮬에만 있어서 미러 트윈에서는 이 한 줄이 TypeError 로 터졌다(깔끔한 거절이 아니라 실패).
+     * 권위(모드) × 성격(주석/액추에이션) 판정은 한 곳에만 둔다.
+     */
+    const ack = await TwinEngine.dispatchCommand(domainId, instanceId, command)
     /* 라이브 구조 변이(resource.add)는 저장 board 에도 반영 — 프로비저닝 편집기·재기동이 추가분을 잃지 않게. */
     if (ack?.accepted && command?.type === 'resource.add') {
       await TwinEngine.syncBoardEquipment(domainId, instanceId).catch(err => console.error('twin syncBoardEquipment fail', err))
     }
-    return { accepted: !!ack?.accepted, error: ack?.error }
+    /* 거절 사유는 **언어 중립 코드**로 함께 돌려준다 — 화면이 `twin.cmderr.<code>` 로 사람 말을 만든다. */
+    return { accepted: !!ack?.accepted, error: ack?.error, errorCode: ack?.errorCode, errorParams: ack?.errorParams }
   }
 
   /** Scenario 채널 — 생성기 시나리오 제어(load/start/pause/setSpeed). */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, { description: 'control twin scenario (load|start|pause|setSpeed)' })
   async controlTwinScenario(
     @Arg('instanceId') instanceId: string,
@@ -44,14 +50,27 @@ export class TwinControlMutation {
     @Arg('scenario', type => ScalarObject, { nullable: true }) scenario?: any
   ): Promise<boolean> {
     const domainId = context.state.domain?.id
-    const inst = TwinEngine.instances[instanceId]
-    if (!inst || inst.domainId !== domainId) return false
-    const runtime = inst.runtime
+    /* 테넌트 격리 — 레지스트리를 직접 색인하지 않는다(키에 도메인이 들어 있다). */
+    if (!TwinEngine.owns(domainId, instanceId)) return false
+    const runtime = TwinEngine.runtime(domainId, instanceId)
     /*
      * 자극 주입 가드 — mirror 트윈(외부 실물이 진실)은 커널 시나리오 엔진이 없다(startLive=projector, runtime 없음).
      * what-if 를 여기에 주입하면 현실을 오염시키므로 거부한다(sim-experiment/sim-world 만 자극 가능). silent throw 방지.
      */
     if (!runtime?.scenario) return false
+    /*
+     * **잘못된 선언은 문 앞에서 막는다.** 예전에는 검증 없이 실었고, 다음 tick 에서 `rate.meanPerHour`
+     * 를 읽다 터져 **서버 프로세스가 내려갔다**(클라이언트가 보낸 값 하나로 앱 전체가 죽었다).
+     * 규칙은 커널이 들고 있다(계약의 주인) — 호스트가 따로 만들면 방언이 생긴다.
+     */
+    if (action === 'load') {
+      const v = validateScenario(scenario)
+      if (v.ok === false) {
+        /* 사유를 로그로 남긴다 — 이 뮤테이션의 반환은 Boolean 계약이라 사유를 실어 보낼 자리가 없다. */
+        console.warn(`[twin] scenario rejected for "${instanceId}": ${v.errorCode} ${JSON.stringify(v.errorParams ?? {})}`)
+        return false
+      }
+    }
     if (action === 'load' && scenario) runtime.scenario.load(scenario)
     else if (action === 'start') runtime.scenario.start()
     else if (action === 'pause') runtime.scenario.pause()

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

@@ -1,4 +1,4 @@
-import { Arg, Ctx, Int, Mutation, Query, Resolver } from 'type-graphql'
+import { Arg, Ctx, Int, Mutation, Query, Resolver, Directive} from 'type-graphql'
 
 import { getRepository, ScalarObject } from '@things-factory/shell'
 
@@ -90,7 +90,7 @@ export class TwinForecastQuery {
     const k = at
       ? await TwinEngine.buildForecastKernelAt(domainId, instanceId, at)
       : TwinEngine.owns(domainId, instanceId)
-        ? TwinEngine.kernel(instanceId)
+        ? TwinEngine.kernel(domainId, instanceId)
         : undefined
     if (!k) return null
 
@@ -228,6 +228,7 @@ export class TwinForecastQuery {
    * assimilation-lite: 잔차(innovation)를 되먹여 추정치를 현실로. per-instance(클라가 co-located 합산).
    * 반환: 학습된 보정 + before/after 정확도(효과 정량화). 저장은 인메모리(세션) — DB 영속은 후속.
    */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => ScalarObject, { description: 'Learn a forecast calibration (bias + band) from the gap trend and persist it so future forecasts apply it. Returns the calibration + before/after accuracy.' })
   async twinLearnCalibration(
     @Arg('instanceId') instanceId: string,

package/server/service/twin-instance/twin-instance.ts

@@ -2,6 +2,7 @@ import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, Primary
 import { ObjectType, Field, ID, Int } from 'type-graphql'
 
 import { Domain, ScalarObject } from '@things-factory/shell'
+import { boardColumnTransformer } from '../../engine/board-vocabulary.js'
 
 /*
  * TwinInstance — 트윈 인스턴스 레지스트리(재부팅 복구의 앵커).
@@ -45,8 +46,11 @@ export class TwinInstance {
   @Field({ nullable: true, description: "Reality source declaration: 'mirror' (external system is truth, resync on reboot) | 'sim-world' (generated timeline is truth and persists, resume on reboot) | 'sim-experiment' (seed-reproducible, resets on reboot). Absent ⇒ treated as sim-experiment." })
   realityMode?: string
 
-  @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, { nullable: true, description: 'BoardDef blueprint (locations/equipment) required to replay events into state.' })
+  /* 읽을 때 어휘 세대를 흡수한다(`nodes`/`movers`/`equipmentList` → `locations`/`equipment`).  (vocabulary-guard: allow — 세대 이름 없이는 설명할 수 없다.)
+     자리마다 리더를 쓰게 하면 다음에 추가되는 자리가 또 빠지고, 빠진 것은 오류가 아니라 **빈 공장**이라
+     조용하다(2026-08-06: 모델러 엔티티 목록이 통째로 비었다). 상세 `engine/board-vocabulary.ts`. */
+  @Column({ type: 'simple-json', nullable: true, transformer: boardColumnTransformer })
+  @Field(type => ScalarObject, { nullable: true, description: 'BoardDef blueprint (locations/equipment) required to replay events into state. Older stored boards used nodes/movers/equipmentList; they are normalised on read so consumers see one vocabulary.' }) // vocabulary-guard: allow — 옛 어휘를 흡수하는 것이 이 코드의 일이다(세대 이름을 적어야 흡수할 수 있다)
   board?: any
 
   @Column({ nullable: true })

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

@@ -6,6 +6,8 @@ import { buildNextCursor, cursorSortings, getQueryBuilderFromListParams, getRepo
 import { TwinEvent } from '../twin-event/twin-event.js'
 import { TwinEventList } from '../twin-event/twin-event-type.js'
 import { TwinEngine } from '../../engine/index.js'
+import { pickAxes } from '../../engine/state-axes.js'
+import { digestAttentions } from '../../engine/attention-digest.js'
 import { computeTwinKpi, resolveTwinTargets } from '../../engine/kpi-query.js'
 
 /*
@@ -126,7 +128,7 @@ export class TwinJournalQuery {
    */
   @Query(returns => ScalarObject, {
     description:
-      'Windowed business KPI folded from the event journal, for one space (every running twin in it, folded together — averaging per-twin percentiles would be wrong) or one twin: throughput (completed tasks / orders), lead / work / wait time distributions (p50·p90), and per-resource busy ratio. Distinct from twinMetrics, which reports infrastructure throughput (events per second). When toTime is omitted the window ends at the twin\'s own last recorded event time, not wall clock — a simulated twin lives on its own clock, so asking for \'the last hour\' in real time would always find nothing. The basis used is reported in window.basis. Pass groupBy (resource | taskKind | location | order | area | shift) to break the same window down by that perspective. The shift axis is **computed, not stored**: the journal records only times, and the shift is derived from each completion\'s time plus the declared site shifts and time zone — so correcting a shift definition re-counts history correctly instead of leaving it frozen under the old boundaries. Sites that declare no shifts report every group as unknown rather than inventing shift names — per-group numbers use the same rules as the totals, so group counts sum to the total, and groups beyond groupLimit are reported as groups.truncated (how many groups) and groups.truncatedTasks (how much work those groups held) rather than silently dropped. Pass compareTo (previous | yesterday) to fold the same-length window shifted back and get comparison.delta (current minus that window); when the comparison window has no records, comparison.measured is false and no delta is produced rather than reporting zero change. Passing groupBy together with compareTo crosses the two: each group carries prevTasks / deltaTasks / deltaWorkP50Ms, groups absent from the comparison window are flagged isNew (no delta, so growth is not implied), and groups that had work before but none now are returned in groups.disappeared so a stopped area is never silently missing from the table. Area breakdown needs board locations to carry a parent area; when they do not, groups.note says so instead of implying there was no work. When the journal read hits its row cap, eventsCapped is true and every number is a lower bound — narrow the window and ask again rather than reading the smaller figures as a drop in performance. When operational targets are set for the space or instance, `targets` carries the verdicts [{metric, actual, target, direction, met, ratio}] — ratio is normalised so that 1 or more is always good, letting throughput and duration metrics be compared on one scale. A metric with no target, or with no measurement in the window, is absent from `targets` rather than reported as a miss, because a period with no work would otherwise read as a perfect score on duration metrics. Completions are counted in the window they complete; starts are looked up before the window, and any completion whose start was not found is reported in `unpaired` rather than silently dropped.'
+      'Windowed business KPI folded from the event journal, for one space (every running twin in it, folded together — averaging per-twin percentiles would be wrong) or one twin: throughput (completed tasks / orders), lead / work / wait time distributions (p50·p90), and per-resource busy ratio. Distinct from twinMetrics, which reports infrastructure throughput (events per second). When toTime is omitted the window ends at the twin\'s own last recorded event time, not wall clock — a simulated twin lives on its own clock, so asking for \'the last hour\' in real time would always find nothing. The basis used is reported in window.basis. Pass groupBy (resource | taskKind | location | order | area | shift) to break the same window down by that perspective. The shift axis is **computed, not stored**: the journal records only times, and the shift is derived from each completion\'s time plus the declared site shifts and time zone — so correcting a shift definition re-counts history correctly instead of leaving it frozen under the old boundaries. Sites that declare no shifts report every group as unknown rather than inventing shift names — per-group numbers use the same rules as the totals, so group counts sum to the total, and groups beyond groupLimit are reported as groups.truncated (how many groups) and groups.truncatedTasks (how much work those groups held) rather than silently dropped. Pass compareTo (previous | yesterday) to fold the same-length window shifted back and get comparison.delta (current minus that window); when the comparison window has no records, comparison.measured is false and no delta is produced rather than reporting zero change. Passing groupBy together with compareTo crosses the two: each group carries prevTasks / deltaTasks / deltaWorkP50Ms, groups absent from the comparison window are flagged isNew (no delta, so growth is not implied), and groups that had work before but none now are returned in groups.disappeared so a stopped area is never silently missing from the table. Area breakdown needs board locations to carry a parent area; when they do not, groups.note says so instead of implying there was no work. When the journal read hits its row cap, eventsCapped is true and every number is a lower bound — narrow the window and ask again rather than reading the smaller figures as a drop in performance. When operational targets are set for the space or instance, `targets` carries the verdicts [{metric, actual, target, direction, met, ratio}] — ratio is normalised so that 1 or more is always good, letting throughput and duration metrics be compared on one scale. A metric with no target, or with no measurement in the window, is absent from `targets` rather than reported as a miss, because a period with no work would otherwise read as a perfect score on duration metrics. Completions are counted in the window they complete; starts are looked up before the window, and any completion whose start was not found is reported in `unpaired` rather than silently dropped. Pass baselinePeriods (1-14, with baselineStride day | week) to fold the same time-of-day window on each of the last N days (or the same weekday on each of the last N weeks) and get `baseline.metrics` — per metric the distribution of those windows (min / median / max) plus where the current window sits: `rank` (1 = smallest, direction-free) and `standing` (best | better-than-typical | typical | worse-than-typical | worst, which does apply the metric direction). This answers what a single comparison cannot: comparing to yesterday alone is useless if yesterday was also bad. Every requested window is returned in `samples` with `measured` true or false — windows without records are kept and counted (measuredCount vs requested) rather than dropped, so "the last 7 days" never silently means 3. No position is reported when the current window has no value or fewer than two baseline windows were measured; `noPosition` says which, because a missing distribution drawn as neutral would read as "typical". The baseline is produced even when the current window itself has no records, since that is exactly when knowing the usual level matters (a stopped line).'
   })
   async twinKpi(
     @Ctx() context: ResolverContext,
@@ -147,7 +149,11 @@ export class TwinJournalQuery {
     /** 축의 상한(기본 20, 최대 100). 넘치면 잘라내고 잘린 수를 알린다. */
     @Arg('groupLimit', type => Int, { nullable: true }) groupLimit?: number,
     /** 비교 기준 — 같은 길이의 앞 구간(previous)이나 하루 전 같은 시간(yesterday). */
-    @Arg('compareTo', { nullable: true }) compareTo?: string
+    @Arg('compareTo', { nullable: true }) compareTo?: string,
+    /** 여러 구간 동시 비교 — 최근 N 구간의 같은 시간대 분포(1~14). */
+    @Arg('baselinePeriods', type => Int, { nullable: true }) baselinePeriods?: number,
+    /** 분포의 간격 — day(같은 시간대) | week(같은 요일·시간대). 기본 day. */
+    @Arg('baselineStride', { nullable: true }) baselineStride?: string
   ): Promise<any> {
     /* 테넌트 격리 — 트윈 지정이면 소속을 확인한다. 공간 지정이면 대상 해소가 도메인 목록에서
      * 이뤄지므로(computeTwinKpi) 남의 트윈이 섞이지 않는다. 조용한 빈 결과가 아니라 명시 실패. */
@@ -168,7 +174,10 @@ export class TwinJournalQuery {
       lookbackMinutes,
       groupBy: groupBy as any,
       groupLimit,
-      compareTo: compareTo as any
+      compareTo: compareTo as any,
+      ...(baselinePeriods && baselinePeriods > 0
+        ? { baseline: { periods: baselinePeriods, stride: (baselineStride as any) === 'week' ? 'week' : 'day' } }
+        : {})
     })
   }
 
@@ -180,9 +189,30 @@ export class TwinJournalQuery {
     @Arg('instanceId') instanceId: string,
     @Arg('untilRevision', type => Int, { nullable: true }) untilRevision: number,
     @Arg('untilTime', { nullable: true }) untilTime: string,
-    @Ctx() context: ResolverContext
+    @Ctx() context: ResolverContext,
+    /*
+     * 필요한 축만 — 지도는 `locations`·`attentions` 만 쓰는데 상태를 통째로 받고 있었다(실 저널로
+     * 재 보니 트윈 하나가 최대 710KB, 같은 공간에 셋이면 약 2MB). 화면 전용 질의를 만들지 않고
+     * 호출부가 축을 말한다(무방언 — 어휘가 화면 이름이 아니라 상태의 축이다).
+     * 말하지 않으면 자르지 않는다(기존 호출부 무영향).
+     */
+    @Arg('axes', type => [String], { nullable: true }) axes?: string[],
+    /*
+     * 신호는 몇 건만 필요한가 — 레일은 20건을 그리고 나머지는 "N건 더" 라고만 말한다. 그런데 신호가
+     * 많은 트윈은 그 전량이 108KB 다(`hatio-yard` 397건). 상위 N 만 보내고 **전체 개수와 자리별
+     * 최고 심각도는 전량을 근거로** 함께 보낸다 — 레일은 잘라도 되지만 지도 색은 잘라선 안 된다.
+     * 말하지 않으면 자르지 않는다.
+     */
+    @Arg('attentionLimit', type => Int, { nullable: true }) attentionLimit?: number
   ): Promise<any> {
-    return TwinEngine.recover(context.state.domain.id, instanceId, untilRevision ?? undefined, untilTime ?? undefined)
+    const state = await TwinEngine.recover(context.state.domain.id, instanceId, untilRevision ?? undefined, untilTime ?? undefined)
+    const picked = pickAxes(state, axes)
+    /* 오타를 조용히 넘기지 않는다 — 화면이 빈 채로 뜨는 이유를 아무도 모르게 되는 것이 가장 나쁘다. */
+    if (picked.unknown.length) console.warn(`[twin] twinReplay: unknown axes ignored for "${instanceId}": ${picked.unknown.join(', ')}`)
+    if (!attentionLimit || !picked.state?.attentions) return picked.state
+    const d = digestAttentions(picked.state.attentions, attentionLimit)
+    /* 잘랐다는 사실을 값으로 남긴다 — 개수만 줄어들면 화면은 "괜찮아졌다" 로 읽는다. */
+    return { ...picked.state, attentions: d.attentions, attentionTotal: d.attentionTotal, severityByLocation: d.severityByLocation }
   }
 
   @Query(returns => ScalarObject, {

package/server/service/twin-lifecycle/twin-lifecycle-mutation.ts

@@ -1,4 +1,4 @@
-import { Arg, Ctx, Mutation, Query, Resolver } from 'type-graphql'
+import { Arg, Ctx, Mutation, Query, Resolver, Directive} from 'type-graphql'
 
 import { ScalarObject } from '@things-factory/shell'
 
@@ -19,6 +19,7 @@ import { domainCatalog } from './domain-catalog.js'
 @Resolver()
 export class TwinLifecycleMutation {
   /** 프로비저닝(저장, 미기동) — 구조를 레지스트리에 등록만. 재프로비전 시 구조 변경이면 저널 purge(엔진). */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, {
     description: 'Provision (save) a twin instance structure (kind: wms|yms|mes) from a BoardDef without starting it.'
   })
@@ -33,6 +34,7 @@ export class TwinLifecycleMutation {
   }
 
   /** 기동 — board 를 주면 provision+start, 없으면 레지스트리에 저장된 구조로 start. */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, {
     description: 'Start a twin runtime instance and begin the worker tick. If board is given it provisions first; otherwise it starts from the saved registry board.'
   })
@@ -49,14 +51,16 @@ export class TwinLifecycleMutation {
     return true
   }
 
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, { description: 'Stop a running twin runtime instance by its id (only if it belongs to the current domain).' })
   async stopTwinInstance(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<boolean> {
     if (!TwinEngine.owns(context.state.domain.id, instanceId)) return false // 테넌트 격리 — 남의 도메인 트윈 정지 차단
-    await TwinEngine.stop(instanceId)
+    await TwinEngine.stop(context.state.domain.id, instanceId)
     return true
   }
 
   /** 삭제 — 정지 + 레지스트리 삭제 + 저널 purge(domain 스코프). */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, { description: 'Delete a twin instance: stop it, remove the registry entry and purge its event journal.' })
   async deleteTwinInstance(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<boolean> {
     await TwinEngine.remove(context.state.domain.id, instanceId)
@@ -64,6 +68,18 @@ export class TwinLifecycleMutation {
   }
 
   /** 관리 목록 — 등록된 인스턴스 전체(kind/status/running/revision/노드·무버 수). 데이터 없으면 빈 배열. */
+  /**
+   * **이 공간의 트윈 id 들** — 한 현실을 여러 렌즈가 비추므로 공간을 물으면 그 렌즈 전부를 답한다.
+   *
+   * 화면이 전체 목록을 받아 걸러 쓰던 규칙을 서버로 모은다. 예측 화면은 같은 확장을 한 파일에서
+   * **두 번** 복제하고 있었고, 규칙이 흩어지면 한쪽만 고쳐진다. 떠 있지 않은 것도 포함한다 —
+   * 공간에 무엇이 있는지는 기동 여부와 다른 사실이다.
+   */
+  @Query(returns => [String], { description: 'Ids of the twins that live in a space (all its lenses), running or not.' })
+  async twinSpaceInstanceIds(@Arg('spaceId') spaceId: string, @Ctx() context: ResolverContext): Promise<string[]> {
+    return TwinEngine.instanceIdsOfSpace(context.state.domain.id, spaceId)
+  }
+
   @Query(returns => [ScalarObject], { description: 'List provisioned twin instances in the current domain with management metadata.' })
   async twinInstanceList(@Ctx() context: ResolverContext): Promise<any[]> {
     return TwinEngine.list(context.state.domain.id)

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

@@ -14,7 +14,7 @@ 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).' })

package/server/service/twin-space/twin-space-resolver.ts

@@ -1,4 +1,4 @@
-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'
 
@@ -47,6 +47,7 @@ export class TwinSpaceResolver {
     return { spaceId: r.spaceId, name: r.name, description: r.description, geo: r.geo, timezone: r.timezone, primaryRepresentationId: r.primaryRepresentationId, content: r.content, representations }
   }
 
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, { description: 'Create or update a Space (name/description/geo/timezone/primaryRepresentationId).' })
   async saveTwinSpace(
     @Arg('spaceId') spaceId: string,
@@ -62,6 +63,7 @@ export class TwinSpaceResolver {
     return true
   }
 
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, { description: 'Delete a Space and its representations/areas.' })
   async deleteTwinSpace(@Arg('spaceId') spaceId: string, @Ctx() context: ResolverContext): Promise<boolean> {
     const domainId = context.state.domain.id
@@ -92,6 +94,7 @@ export class TwinSpaceResolver {
     return rows.map(a => ({ areaId: a.areaId, name: a.name, type: a.type, parentId: a.parentId, layout: a.layout }))
   }
 
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, { description: 'Create/update a logical area (shared across representations). (area unification)' })
   async saveTwinArea(
     @Arg('spaceId') spaceId: string,
@@ -124,6 +127,7 @@ export class TwinSpaceResolver {
    * 참조: 자식 area(parentId) · 표현별 폴리곤(TwinSpaceArea binding.groupId/areaId).
    * (노드/엔티티 담김·drillTo 참조는 P2 areaId 배선 후 확장.)
    */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, { description: 'Delete a logical area only if unreferenced (reference-counted). Throws if referenced. (area unification)' })
   async deleteTwinArea(@Arg('spaceId') spaceId: string, @Arg('areaId') areaId: string, @Ctx() context: ResolverContext): Promise<boolean> {
     const domainId = context.state.domain.id
@@ -146,6 +150,7 @@ export class TwinSpaceResolver {
   }
 
   /* ── Representation ─────────────────────────────────────────────── */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => ScalarObject, { description: 'Create/update a representation (map|image|board). Returns {id}.' })
   async saveSpaceRepresentation(
     @Arg('spaceId') spaceId: string,
@@ -161,6 +166,7 @@ export class TwinSpaceResolver {
     return { ok: true, id: saved.id }
   }
 
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, { description: 'Delete a representation and its areas.' })
   async deleteSpaceRepresentation(@Arg('id') id: string, @Ctx() context: ResolverContext): Promise<boolean> {
     const domainId = context.state.domain.id
@@ -169,6 +175,7 @@ export class TwinSpaceResolver {
     return true
   }
 
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, { description: 'Set the primary representation of a space.' })
   async setPrimaryRepresentation(@Arg('spaceId') spaceId: string, @Arg('repId') repId: string, @Ctx() context: ResolverContext): Promise<boolean> {
     const domainId = context.state.domain.id
@@ -183,6 +190,7 @@ export class TwinSpaceResolver {
   }
 
   /* ── Area (map/image 폴리곤) ────────────────────────────────────── */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => ScalarObject, { description: 'Create/update a polygon area (geometry + drillTo board + binding). Returns {id}.' })
   async saveSpaceArea(
     @Arg('representationId') representationId: string,
@@ -198,6 +206,7 @@ export class TwinSpaceResolver {
     return { ok: true, id: saved.id }
   }
 
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, { description: 'Delete a polygon area.' })
   async deleteSpaceArea(@Arg('id') id: string, @Ctx() context: ResolverContext): Promise<boolean> {
     await getRepository(TwinSpaceArea).delete({ domain: { id: context.state.domain.id } as any, id } as any)