@things-factory/headless-twin 10.0.9 → 10.0.10

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

@@ -3,8 +3,11 @@ 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 { knobDefaultsFilled } from './reference-master.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'
@@ -13,6 +16,7 @@ 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'
 
@@ -24,7 +28,7 @@ import { listTemplates, getTemplate } from './template-registry.js'
 /**
  * 발견 조회의 시간 상한 — 15초.
  *
- * 어댑터 계약에 시간 제한이 없다. 주소가 틀린 엔드포인트는 답하지 않고, 그러면 화면이 무한히 돈다 —
+ * 어댑터 계약에 시간 제한이 없다. 주소가 틀린 엔드포인트는 답하지 않고, 그러면 화면이 무한히 로딩된다 —
  * 사용자에게는 "실패" 보다 못한 상태다(무엇을 기다리는지 모른 채 기다린다). 실 시스템 조회가 몇 초
  * 걸리는 것은 정상이므로 넉넉히 두되, 끝은 있어야 한다.
  */
@@ -41,6 +45,76 @@ function withTimeout<T>(work: Promise<T>, ms: number): Promise<T> {
   })
 }
 
+/**
+ * 거절을 **사용자 언어로 옮겨 보낸다** — 번역은 한 곳에서 한다.
+ *
+ * ── 왜 서버인가 (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 {
   /** 등록된 레퍼런스 소스 목록(요약 + 이미 인제스트됐는지). */
@@ -76,12 +150,119 @@ 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`
+    )
   }
 
   /** 등록된 트윈 템플릿(파라미터화 아키타입) 목록 — 노브 스키마 포함(클라이언트 폼용). */
@@ -112,10 +293,24 @@ export class TwinReferenceResolver {
        */
       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 })
+      const res = await TwinEngine.ingestMaster(domainId, master, { spaceId }, context.state.user)
       if (start !== false) {
         await TwinEngine.startFromRegistry(domainId, res.instanceId)
         if (scenario) {
@@ -126,10 +321,14 @@ export class TwinReferenceResolver {
           }
         }
       }
-      const warnings = filled.length ? [knobDefaultsFilled(filled), ...res.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')
     }
   }
 
@@ -309,7 +508,7 @@ export class TwinReferenceResolver {
   @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`(순수)가 갖는다.
@@ -335,15 +534,25 @@ export class TwinReferenceResolver {
   /**
    * 트윈 생성 — 레퍼런스에서 사이트 발견 → (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`) — 서로 다른 현장이 조용히 합쳐지는 것을 막는다.
    */
   @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.' })
+  @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)
@@ -355,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
@@ -393,8 +612,9 @@ export class TwinReferenceResolver {
       )
       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-audit/command-audit.ts

@@ -0,0 +1,81 @@
+/*
+ * 커맨드 감사 기록 만들기 (순수) — **누가 무엇을 허락했고, 그래서 어떻게 됐나.**
+ *
+ * 승인 게이트가 앞을 막고, 이 기록이 뒤를 설명한다. 둘 다 있어야 "사람 손을 거쳤다" 를 증명할 수 있다.
+ *
+ * 무엇을 믿는가가 이 기록의 전부다:
+ *  · **신원·시각은 서버가 준다.** 클라이언트가 말한 신원을 그대로 적으면 위조가 자유로워 아무것도
+ *    증명하지 못한다. 세션이 아는 사용자와 서버 시각만 쓴다.
+ *  · **의도는 클라이언트가 준다** — 출처(origin)·근거(reason). 서버가 알 수 없는 정보이고,
+ *    위조되더라도 신원 증명을 훼손하지 않는다.
+ */
+
+export type CommandOrigin = 'user' | 'ai' | 'automation' | 'unknown'
+
+export type CommandAuditInput = {
+  /** 클라이언트가 실어 보낸 커맨드(신뢰하지 않는 부분을 포함한 원본). */
+  command: any
+  /** 커널 판정. */
+  ack: { accepted?: boolean; errorCode?: string; error?: string }
+  /** 세션이 아는 사용자 — **서버만 채운다.** */
+  actor?: { id?: string; email?: string; name?: string }
+  /** 서버 시각. 호출부가 주입해 테스트가 시간을 고정할 수 있게 한다. */
+  at: Date
+}
+
+/** `TwinAuditEvent` 에 그대로 넣을 수 있는 모양(엔티티를 몰라도 되게 순수하게 둔다). */
+export type CommandAuditRow = {
+  eventTime: Date
+  commandId?: string
+  commandType?: string
+  origin: CommandOrigin
+  reason?: string
+  actorId?: string
+  actorEmail?: string
+  actorName?: string
+  accepted: boolean
+  errorCode?: string
+  args?: any
+  argsTruncated: boolean
+}
+
+/** 신뢰할 수 있는 출처 표기로 정규화 — 모르는 값은 지어내지 않고 'unknown' 으로 둔다. */
+export function normalizeOrigin(v: unknown): CommandOrigin {
+  return v === 'user' || v === 'ai' || v === 'automation' ? v : 'unknown'
+}
+
+/** args 직렬화 상한(문자). 넘으면 자르되 잘랐다고 표시한다. */
+const ARGS_MAX = 4000
+
+export function buildCommandAudit(input: CommandAuditInput): CommandAuditRow {
+  const { command, ack, actor, at } = input
+  const argsText = safeJson(command?.args)
+  const truncated = argsText !== null && argsText.length > ARGS_MAX
+  return {
+    eventTime: at,
+    commandId: str(command?.commandId),
+    commandType: str(command?.type),
+    origin: normalizeOrigin(command?.origin),
+    reason: str(command?.reason),
+    /* 신원 — 세션 값만. 커맨드에 실려 온 신원 주장은 쳐다보지 않는다. */
+    actorId: str(actor?.id),
+    actorEmail: str(actor?.email),
+    actorName: str(actor?.name),
+    /* 결과 — 승인했는데 커널이 거절한 것도 감사 대상이다(무엇을 시도했는지가 남아야 한다). */
+    accepted: !!ack?.accepted,
+    errorCode: str(ack?.errorCode),
+    /* 인자는 원형 그대로. 너무 크면 잘린 문자열로 두되 잘랐다고 말한다. */
+    args: truncated ? argsText!.slice(0, ARGS_MAX) : command?.args ?? undefined,
+    argsTruncated: truncated
+  }
+}
+
+const str = (v: unknown): string | undefined => (typeof v === 'string' && v ? v : undefined)
+
+function safeJson(v: unknown): string | null {
+  try {
+    return v === undefined ? null : JSON.stringify(v)
+  } catch {
+    return null /* 순환 참조 등 — 못 재면 자르지 않는다(원본을 그대로 둔다) */
+  }
+}

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

@@ -0,0 +1,5 @@
+import { TwinAuditEvent } from './twin-audit-event.js'
+import { TwinAuditQuery } from './twin-audit-query.js'
+
+export const entities = [TwinAuditEvent]
+export const resolvers = [TwinAuditQuery]

package/server/service/twin-audit/twin-audit-event.ts

@@ -0,0 +1,112 @@
+import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn } from 'typeorm'
+import { ObjectType, Field, ID } from 'type-graphql'
+
+import { Domain, ScalarObject } from '@things-factory/shell'
+
+/*
+ * TwinAuditEvent — **사람이 무엇을 허락했는가.**
+ *
+ * ── 왜 저널(TwinEvent)이 아닌가 ───────────────────────────────────────────────
+ * 처음에는 저널에 함께 넣었다. "감사는 원장에서 하니까" 라는 이유였는데, 그건 **화면의 편의**였고
+ * 저장 구조를 정할 근거가 못 됐다. 넣자마자 예외가 넷 생겼다 — 리플레이에서 빼고, 백필에서 빼고,
+ * 원장 거래 분류에서 빼고, 원장 렌더에서 갈랐다. **예외가 넷이면 설계가 "여기 아니다" 라고 말하는 것이다.**
+ *
+ * 갈라 두면 예외가 0 이고, 오히려 얻는다:
+ *  · 행위자가 **컬럼**이 된다 — "누가 승인한 것 전부" 는 감사의 기본 질문인데 payload 안에서는 못 찾았다
+ *  · revision 이 없다. 저널에서는 그 칸을 비워 "상태가 아님" 을 뜻하게 썼는데, 없음을 종류 표시로
+ *    쓰는 것이 여러 번 문제를 냈다(백필의 `bizStep IS NULL = 옛 행` 전제가 이것 때문에 깨졌다)
+ *  · bizStep 오염이 없다 — 저널의 키 추출기는 값이 없으면 이벤트 타입으로 대체하므로,
+ *    감사 행을 태우면 CBV 표준 어휘 컬럼에 `governance.command` 가 박힌다
+ *
+ * ── 무엇을 믿는가 ────────────────────────────────────────────────────────────
+ * **신원·시각은 서버가 각인한다.** 클라이언트가 말한 신원을 그대로 적으면 위조가 자유로워 그 기록은
+ * 아무것도 증명하지 못한다. 세션이 아는 사용자와 서버 시각만 신뢰한다.
+ * 클라이언트에서 받는 것은 **의도**뿐이다 — 어디서 시작됐나(origin), 왜 하나(reason).
+ */
+@Entity()
+/* 목록 기본 정렬 — 최근 것부터. 감사는 "요즘 무슨 일이 있었나" 로 시작한다. */
+@Index('ix_twin_audit_0', (e: TwinAuditEvent) => [e.domain, e.instanceId, e.eventTime], { unique: false })
+/* 행위자로 찾기 — 저널에 있을 때는 불가능했던 질문("김현장이 승인한 것 전부"). */
+@Index('ix_twin_audit_1', (e: TwinAuditEvent) => [e.domain, e.actorEmail, e.eventTime], { unique: false })
+@ObjectType({ description: 'Audit record of a twin command: who approved what, and what the kernel answered.' })
+export class TwinAuditEvent {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { description: 'Unique identifier of the audit record.' })
+  readonly id: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })
+  domain?: Domain
+
+  @RelationId((e: TwinAuditEvent) => e.domain)
+  domainId?: string
+
+  @Column()
+  @Field({ description: 'Twin runtime instance the command was aimed at.' })
+  instanceId: string
+
+  /*
+   * 서버 시각. 클라이언트 시계를 믿지 않는다 — 기록의 시간축이 단말 설정에 좌우되면 안 된다.
+   *
+   * `datetime` 을 쓴다. `timestamp` 는 **sqlite 가 지원하지 않아** 5개 드라이버 공통이 아니다
+   * (실제로 그렇게 썼다가 DB 를 쓰는 검사 33개가 한꺼번에 터졌다).
+   */
+  @Column({ type: 'datetime' })
+  @Field({ description: 'Server time when the command was dispatched.' })
+  eventTime: Date
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Client-supplied command id, for correlating with kernel logs.' })
+  commandId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Command type (e.g. order.hold, equipment.repair).' })
+  commandType?: string
+
+  /* 'user' | 'ai' | 'automation' | 'unknown'. 모르면 unknown 이지 사람이 한 것으로 치지 않는다. */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: "Where the command originated: 'user' | 'ai' | 'automation' | 'unknown'." })
+  origin?: string
+
+  @Column({ type: 'text', nullable: true })
+  @Field({ nullable: true, description: 'Why this action — the rationale shown on the approval card.' })
+  reason?: string
+
+  /* ── 신원: 세션에서만 온다 ── */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Approving user id, stamped by the server from the session.' })
+  actorId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Approving user email, stamped by the server from the session.' })
+  actorEmail?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Approving user name, stamped by the server from the session.' })
+  actorName?: string
+
+  /* ── 결과: 거절도 남긴다 ── */
+  @Column({ default: false })
+  @Field({ description: 'Whether the kernel accepted the command.' })
+  accepted: boolean
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Language-neutral rejection code when the kernel refused.' })
+  errorCode?: string
+
+  /**
+   * 명령 인자 — **원형 그대로.** 무엇에 대한 명령이었는지가 감사의 핵심이라 요약하지 않는다.
+   * 지나치게 크면 자르되 `argsTruncated` 로 잘랐다는 사실을 남긴다(조용히 버리지 않는다).
+   */
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, { nullable: true, description: 'Command arguments as given.' })
+  args?: any
+
+  @Column({ default: false })
+  @Field({ description: 'True when args were too large and stored truncated.' })
+  argsTruncated: boolean
+
+  @CreateDateColumn()
+  @Field({ nullable: true, description: 'Timestamp when the audit row was written.' })
+  createdAt?: Date
+}