@things-factory/headless-twin 10.0.8 → 10.0.10

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

@@ -3,10 +3,31 @@ export declare class TwinReferenceResolver {
     referenceSources(context: ResolverContext): Promise<any[]>;
     /** 소스를 인제스트 → 공간 + 인스턴스 생성(provision). start 면 기동까지. */
     importFromReference(source: string, context: ResolverContext, start?: boolean): Promise<any>;
+    /**
+     * **원본에서 다시 읽는다** — 이 트윈의 구조를 지금의 원본 모습으로 갱신한다.
+     *
+     * ── 왜 진입점이 하나여야 하나 ──────────────────────────────────────────────
+     * 지금까지 다시 읽기는 **만드는 경로에 얹혀 있었다**(`importFromReference`·`createFromTemplate`).
+     * 그래서 이미 있는 트윈을 갱신하려면 만들 때 무엇을 골랐는지 사람이 기억해 같은 화면을 다시
+     * 거쳐야 했고, 템플릿으로 세운 트윈은 노브를 어디에도 안 남겨서 **아예 갱신할 방법이 없었다.**
+     * 원천이 무엇이든 트윈 자신이 기억하게 하고(`TwinInstance.origin`), 여기 한 곳에서 그것을 따른다.
+     *
+     * ── 무엇이 일어나나 ────────────────────────────────────────────────────────
+     * 원본에서 마스터를 다시 얻어 인제스트에 그대로 태운다. 그다음은 인제스트가 아는 일이다 —
+     * 구조가 달라졌으면 새 리비전이 남고, 구조 행이 다시 그려지고, **실행 중인 미러는 멈추지 않고
+     * 전환한다.** 실행 중인 시뮬레이션은 거절된다(조건이 바뀐 실험은 다른 실험이다).
+     *
+     * ── 못 할 때는 못 한다고 한다 ──────────────────────────────────────────────
+     * `origin` 이 없는 트윈(이 자리가 생기기 전에 만들어진 것)은 다시 읽을 수 없다. 짐작으로
+     * 템플릿을 고르거나 첫 레퍼런스를 집지 않는다 — 엉뚱한 원본으로 현장을 덮는 것이 훨씬 나쁘다.
+     */
+    resyncTwin(instanceId: string, context: ResolverContext): Promise<any>;
+    /** 기억해 둔 원천에서 마스터를 다시 얻는다 — 어댑터든 템플릿이든 이 한 곳에서 갈린다. */
+    private masterFromOrigin;
     /** 등록된 트윈 템플릿(파라미터화 아키타입) 목록 — 노브 스키마 포함(클라이언트 폼용). */
     twinTemplates(_context: ResolverContext): Promise<any[]>;
     /** 템플릿 + 노브 → 합성 마스터 → 인제스트(+기동+시나리오). 레퍼런스 import 와 같은 경로, 원천만 합성. */
-    createFromTemplate(templateId: string, params: any, context: ResolverContext, start?: boolean): Promise<any>;
+    createFromTemplate(templateId: string, params: any, context: ResolverContext, start?: boolean, spaceId?: string): Promise<any>;
     twinReferences(context: ResolverContext): Promise<any[]>;
     referenceAdapterTypes(): string[];
     /**
@@ -29,10 +50,19 @@ export declare class TwinReferenceResolver {
      * P1 은 대개 N=1(virtual/단일). start 면 각 인스턴스 기동. 라이브 피드·mode 는 face2-inbound-live 소유.
      */
     /** 레퍼런스가 노출하는 사이트/공장 발견 — 트윈 생성 시 "어느 공장" 선택용(§2.2). */
-    discoverReferenceSites(source: string, context: ResolverContext): Promise<any[]>;
+    discoverReferenceSites(source: string, context: ResolverContext): Promise<any>;
     /**
      * 트윈 생성 — 레퍼런스에서 사이트 발견 → (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`) — 서로 다른 현장이 조용히 합쳐지는 것을 막는다.
      */
-    importTwinReference(source: string, context: ResolverContext, siteIds?: string[], start?: boolean, live?: boolean): Promise<any>;
+    importTwinReference(source: string, context: ResolverContext, siteIds?: string[], start?: boolean, live?: boolean, spaceId?: string): Promise<any>;
 }

package/dist-server/service/reference/reference-resolver.js

@@ -5,16 +5,101 @@ const tslib_1 = require("tslib");
 const type_graphql_1 = require("type-graphql");
 const shell_1 = require("@things-factory/shell");
 const index_js_1 = require("../../engine/index.js");
+const twin_kernel_1 = require("@operato/twin-kernel");
+const knob_defaults_js_1 = require("./knob-defaults.js");
+const reference_master_js_1 = require("./reference-master.js");
 const twin_instance_js_1 = require("../twin-instance/twin-instance.js");
 const twin_reference_js_1 = require("./twin-reference.js");
 const reference_registry_js_1 = require("./reference-registry.js");
 const reference_adapter_js_1 = require("./reference-adapter.js");
+const discovery_result_js_1 = require("./discovery-result.js");
+const ingest_space_js_1 = require("./ingest-space.js");
 const reference_live_js_1 = require("./reference-live.js");
 const template_registry_js_1 = require("./template-registry.js");
 /*
  * Face2 레퍼런스 인제스트 채널(ADR-0018) — 등록된 레퍼런스 소스를 열거하고, 골라서 트윈으로 인제스트.
  * "연결하고 내 것을 불러온다" — 엔티티는 레퍼런스에서 오지 손배선/발명이 아니다.
  */
+/**
+ * 발견 조회의 시간 상한 — 15초.
+ *
+ * 어댑터 계약에 시간 제한이 없다. 주소가 틀린 엔드포인트는 답하지 않고, 그러면 화면이 무한히 로딩된다 —
+ * 사용자에게는 "실패" 보다 못한 상태다(무엇을 기다리는지 모른 채 기다린다). 실 시스템 조회가 몇 초
+ * 걸리는 것은 정상이므로 넉넉히 두되, 끝은 있어야 한다.
+ */
+const DISCOVER_TIMEOUT_MS = 15_000;
+const TIMEOUT = 'discover-timeout';
+function withTimeout(work, ms) {
+    return new Promise((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, e, fallback) {
+    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, effective, domainId, spaceId) {
+    const targets = (knobs ?? []).filter(k => k?.type === 'siteEquipment');
+    if (!targets.length)
+        return [];
+    const out = [];
+    let ids;
+    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 (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).find({ where: { domain: { id: domainId }, spaceId } });
+            const seen = new Map();
+            for (const r of rows) {
+                for (const e of (0, twin_kernel_1.readBoardEquipment)(r.model ?? {})) {
+                    if (!e?.id || seen.has(String(e.id)))
+                        continue;
+                    seen.set(String(e.id), { id: String(e.id), kind: String(e.kind ?? '') });
+                }
+            }
+            ids = [...seen.values()];
+        }
+        effective[k.key] = ids;
+        out.push({ key: k.key, count: ids.length });
+    }
+    return out;
+}
 let TwinReferenceResolver = class TwinReferenceResolver {
     /** 등록된 레퍼런스 소스 목록(요약 + 이미 인제스트됐는지). */
     async referenceSources(context) {
@@ -30,7 +115,7 @@ let TwinReferenceResolver = class TwinReferenceResolver {
                 areaCount: m.locations.filter(l => l.role === 'area' || l.role === 'both').length,
                 equipmentCount: (m.equipment ?? []).length,
                 imported: !!reg,
-                running: !!index_js_1.TwinEngine.instances[m.source]
+                running: index_js_1.TwinEngine.owns(domainId, m.source)
             });
         }
         return out;
@@ -42,42 +127,169 @@ let TwinReferenceResolver = class TwinReferenceResolver {
             return { ok: false, error: `unknown reference source: ${source}` };
         const domainId = context.state.domain.id;
         try {
-            const res = await index_js_1.TwinEngine.ingestMaster(domainId, master);
+            /* 어디서 왔는지 남긴다 — 이것이 없으면 이 트윈은 두 번 다시 읽을 수 없다.
+               이 경로는 **메모리에 등록된 마스터 하나**를 그대로 쓰므로 사이트 서술자가 없다(사이트 정체를
+               적을 것이 없다). 다시 읽기도 같은 등록본을 집으므로 사이트를 찾을 필요가 없다. */
+            const res = await index_js_1.TwinEngine.ingestMaster(domainId, { ...master, origin: { kind: 'reference', source } }, undefined, context.state.user);
             if (start)
                 await index_js_1.TwinEngine.startFromRegistry(domainId, res.instanceId);
             return { ok: true, instanceId: res.instanceId, spaceId: res.spaceId, warnings: res.warnings };
         }
         catch (e) {
-            return { ok: false, error: e?.message || 'ingest failed' };
+            return refusal(context, e, 'ingest failed');
         }
     }
+    /**
+     * **원본에서 다시 읽는다** — 이 트윈의 구조를 지금의 원본 모습으로 갱신한다.
+     *
+     * ── 왜 진입점이 하나여야 하나 ──────────────────────────────────────────────
+     * 지금까지 다시 읽기는 **만드는 경로에 얹혀 있었다**(`importFromReference`·`createFromTemplate`).
+     * 그래서 이미 있는 트윈을 갱신하려면 만들 때 무엇을 골랐는지 사람이 기억해 같은 화면을 다시
+     * 거쳐야 했고, 템플릿으로 세운 트윈은 노브를 어디에도 안 남겨서 **아예 갱신할 방법이 없었다.**
+     * 원천이 무엇이든 트윈 자신이 기억하게 하고(`TwinInstance.origin`), 여기 한 곳에서 그것을 따른다.
+     *
+     * ── 무엇이 일어나나 ────────────────────────────────────────────────────────
+     * 원본에서 마스터를 다시 얻어 인제스트에 그대로 태운다. 그다음은 인제스트가 아는 일이다 —
+     * 구조가 달라졌으면 새 리비전이 남고, 구조 행이 다시 그려지고, **실행 중인 미러는 멈추지 않고
+     * 전환한다.** 실행 중인 시뮬레이션은 거절된다(조건이 바뀐 실험은 다른 실험이다).
+     *
+     * ── 못 할 때는 못 한다고 한다 ──────────────────────────────────────────────
+     * `origin` 이 없는 트윈(이 자리가 생기기 전에 만들어진 것)은 다시 읽을 수 없다. 짐작으로
+     * 템플릿을 고르거나 첫 레퍼런스를 집지 않는다 — 엉뚱한 원본으로 현장을 덮는 것이 훨씬 나쁘다.
+     */
+    async resyncTwin(instanceId, context) {
+        const domainId = context.state.domain.id;
+        const inst = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } });
+        if (!inst)
+            return { ok: false, error: `unknown twin: ${instanceId}` };
+        const origin = inst.origin;
+        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 index_js_1.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) {
+            return refusal(context, e, 'resync failed');
+        }
+    }
+    /** 기억해 둔 원천에서 마스터를 다시 얻는다 — 어댑터든 템플릿이든 이 한 곳에서 갈린다. */
+    async masterFromOrigin(domainId, origin, instanceId) {
+        if (origin.kind === 'template') {
+            const tpl = (0, template_registry_js_1.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 = (0, reference_registry_js_1.getReference)(origin.source);
+        if (inMemory)
+            return { ...inMemory, origin };
+        const ref = await (0, shell_1.getRepository)(twin_reference_js_1.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 = (0, reference_adapter_js_1.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 = (0, reference_master_js_1.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`);
+    }
     /** 등록된 트윈 템플릿(파라미터화 아키타입) 목록 — 노브 스키마 포함(클라이언트 폼용). */
     async twinTemplates(_context) {
         return (0, template_registry_js_1.listTemplates)().map(t => ({ id: t.id, label: t.label, system: t.system, description: t.description, detail: t.detail, knobs: t.knobs }));
     }
     /** 템플릿 + 노브 → 합성 마스터 → 인제스트(+기동+시나리오). 레퍼런스 import 와 같은 경로, 원천만 합성. */
-    async createFromTemplate(templateId, params, context, start) {
+    async createFromTemplate(templateId, params, context, start, spaceId) {
         const tpl = (0, template_registry_js_1.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 index_js_1.TwinEngine.ingestMaster(domainId, master);
+            /*
+             * **빠진 노브를 서버가 채운다.** 기본값을 아는 곳은 노브 스키마(계약)인데 그것을 적용하는 곳이
+             * 위자드뿐이었다 — 그래서 화면을 거치지 않는 호출자(AI·스크립트·API)가 파라미터를 일부만 주면
+             * 템플릿 안에서 발생률이 0 이 되고 **아무것도 하지 않는 트윈**이 조용히 만들어졌다.
+             * 채운 노브 이름은 경고로 함께 돌려준다 — 조용히 채우는 것도 조용히 비우는 것만큼 위험하다.
+             */
+            const filled = (0, knob_defaults_js_1.filledKnobKeys)(tpl.knobs, params);
+            const effective = (0, knob_defaults_js_1.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 index_js_1.TwinEngine.ingestMaster(domainId, master, { spaceId }, context.state.user);
             if (start !== false) {
                 await index_js_1.TwinEngine.startFromRegistry(domainId, res.instanceId);
                 if (scenario) {
-                    const runtime = index_js_1.TwinEngine.runtime(res.instanceId);
+                    const runtime = index_js_1.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 ? [(0, reference_master_js_1.knobDefaultsFilled)(filled)] : []),
+                ...adopted.filter(a => a.count > 0).map(a => (0, reference_master_js_1.siteEquipmentAdopted)(a.key, a.count)),
+                ...res.warnings
+            ];
+            return { ok: true, instanceId: res.instanceId, spaceId: res.spaceId, warnings };
         }
         catch (e) {
-            return { ok: false, error: e?.message || 'template instantiation failed' };
+            return refusal(context, e, 'template instantiation failed');
         }
     }
     /* ── 레퍼런스 관리(엔티티 기반·테넌트 스코프) — reference-management P1 ────────
@@ -137,7 +349,7 @@ let TwinReferenceResolver = class TwinReferenceResolver {
             .filter(p => instMap.has(p.instanceId))
             .map(p => {
             const inst = instMap.get(p.instanceId);
-            return { instanceId: p.instanceId, spaceId: p.spaceId, siteId: p.siteId, kind: inst.kind, status: inst.status, running: !!index_js_1.TwinEngine.instances?.[p.instanceId] };
+            return { instanceId: p.instanceId, spaceId: p.spaceId, siteId: p.siteId, kind: inst.kind, status: inst.status, running: index_js_1.TwinEngine.owns(domainId, p.instanceId) };
         });
         return {
             source: r.source,
@@ -230,24 +442,47 @@ let TwinReferenceResolver = class TwinReferenceResolver {
      */
     /** 레퍼런스가 노출하는 사이트/공장 발견 — 트윈 생성 시 "어느 공장" 선택용(§2.2). */
     async discoverReferenceSites(source, context) {
+        /*
+         * **"못 찾았다" 와 "없다" 를 구분한다.** 예전에는 넷을 빈 배열 하나로 접었고(레퍼런스 없음·어댑터
+         * 미상·조회 실패·정말 0건), 화면은 그 모두를 "사이트를 찾지 못했습니다" 라고만 말했다. 실 시스템
+         * 연결에서 가장 자주 막히는 자리인데 자격이 틀렸는지 주소가 틀렸는지 알 수 없었다.
+         * 판정과 문장 형태는 `discovery-result`(순수)가 갖는다.
+         */
         const ref = await (0, shell_1.getRepository)(twin_reference_js_1.TwinReference).findOne({ where: { domain: { id: context.state.domain.id }, source } });
         if (!ref)
-            return [];
+            return (0, discovery_result_js_1.failed)((0, discovery_result_js_1.referenceNotFound)(source));
         const adapter = (0, reference_adapter_js_1.getAdapter)(ref.adapterType);
         if (!adapter)
-            return [];
+            return (0, discovery_result_js_1.failed)((0, discovery_result_js_1.adapterUnknown)(ref.adapterType, source));
         try {
-            return await adapter.discoverSites(ref.connectionConfig ?? {});
+            /*
+             * **기다려도 답이 없으면 사유를 준다.** 어댑터 계약에 시간 제한이 없어서, 주소가 틀린 엔드포인트는
+             * 화면을 무한히 돌게 만들었다 — 무한히 도는 화면은 조용한 실패의 다른 얼굴이다.
+             * 상한은 여기서 정한다(어댑터마다 다르게 두면 사용자가 어느 것을 기다리는지 알 수 없다).
+             */
+            const sites = await withTimeout(adapter.discoverSites(ref.connectionConfig ?? {}), DISCOVER_TIMEOUT_MS);
+            return (0, discovery_result_js_1.discovered)(sites);
         }
-        catch {
-            return [];
+        catch (e) {
+            if (e?.code === TIMEOUT)
+                return (0, discovery_result_js_1.failed)((0, discovery_result_js_1.discoveryTimedOut)(source, DISCOVER_TIMEOUT_MS / 1000));
+            return (0, discovery_result_js_1.failed)((0, discovery_result_js_1.discoveryFailed)(source, (0, discovery_result_js_1.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`) — 서로 다른 현장이 조용히 합쳐지는 것을 막는다.
      */
-    async importTwinReference(source, context, siteIds, start, live) {
+    async importTwinReference(source, context, siteIds, start, live, spaceId) {
         const domainId = context.state.domain.id;
         const repo = (0, shell_1.getRepository)(twin_reference_js_1.TwinReference);
         const ref = await repo.findOne({ where: { domain: { id: domainId }, source } });
@@ -261,12 +496,18 @@ let TwinReferenceResolver = class TwinReferenceResolver {
             let sites = await adapter.discoverSites(cfg);
             if (siteIds?.length)
                 sites = sites.filter(s => siteIds.includes(s.siteId));
+            /* 아무것도 쓰기 전에 거절한다 — 한 사이트를 넘으면 "이 현장에 더한다" 가 성립하지 않는다. */
+            const refusal = (0, ingest_space_js_1.refuseImportSpace)(sites.length, spaceId);
+            if (refusal)
+                return { ok: false, error: refusal.message, errorCode: refusal.code, errorParams: refusal.params };
             const instances = [];
             const failed = [];
             for (const site of sites) {
                 try {
                     const master = await adapter.fetchMaster(cfg, site);
-                    const res = await index_js_1.TwinEngine.ingestMaster(domainId, master);
+                    /* 어느 레퍼런스의 **어느 사이트**에서 왔는지 남긴다 — 다시 읽기가 같은 어댑터·같은 사이트로 돌아오려면
+                       사이트 정체가 있어야 한다(`source` 는 참조 이름이라 사이트 전부에 같다). */
+                    const res = await index_js_1.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 (0, reference_live_js_1.startReferenceLiveFeed)(domainId, ref.adapterType, cfg, site, res.instanceId) : false;
@@ -288,14 +529,21 @@ let TwinReferenceResolver = class TwinReferenceResolver {
             await repo.update({ id: ref.id }, {
                 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) => f.siteId).join(', ')}` : null,
                 scopeSpec: { ...(ref.scopeSpec ?? {}), produced: [...prev, ...producedNew] }
             });
             return { ok: instances.length > 0, instances, failed };
         }
         catch (e) {
+            /* 레퍼런스 행에는 **영어 canonical** 을 남긴다 — 저장되는 값은 언어중립이어야 다시 읽을 수 있다. */
             await repo.update({ id: ref.id }, { status: 'error', lastError: e?.message ?? 'ingest failed' });
-            return { ok: false, error: e?.message ?? 'ingest failed' };
+            return refusal(context, e, 'ingest failed');
         }
     }
 };
@@ -308,6 +556,7 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinReferenceResolver.prototype, "referenceSources", null);
 tslib_1.__decorate([
+    (0, type_graphql_1.Directive)('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)'),
     (0, type_graphql_1.Mutation)(returns => shell_1.ScalarObject, { description: 'Ingest a registered reference source into a twin (space + instance). Optionally start it.' }),
     tslib_1.__param(0, (0, type_graphql_1.Arg)('source')),
     tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
@@ -316,6 +565,17 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:paramtypes", [String, Object, Boolean]),
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinReferenceResolver.prototype, "importFromReference", null);
+tslib_1.__decorate([
+    (0, type_graphql_1.Directive)('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)'),
+    (0, type_graphql_1.Mutation)(returns => shell_1.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."
+    }),
+    tslib_1.__param(0, (0, type_graphql_1.Arg)('instanceId')),
+    tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [String, Object]),
+    tslib_1.__metadata("design:returntype", Promise)
+], TwinReferenceResolver.prototype, "resyncTwin", null);
 tslib_1.__decorate([
     (0, type_graphql_1.Query)(returns => [shell_1.ScalarObject], { description: 'List registered twin templates (parameterized archetypes) with their knob schema.' }),
     tslib_1.__param(0, (0, type_graphql_1.Ctx)()),
@@ -324,13 +584,15 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinReferenceResolver.prototype, "twinTemplates", null);
 tslib_1.__decorate([
+    (0, type_graphql_1.Directive)('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)'),
     (0, type_graphql_1.Mutation)(returns => shell_1.ScalarObject, { description: 'Instantiate a twin template with params → synthetic master → ingest (+start+scenario). Returns {ok, instanceId, spaceId}.' }),
     tslib_1.__param(0, (0, type_graphql_1.Arg)('templateId')),
     tslib_1.__param(1, (0, type_graphql_1.Arg)('params', type => shell_1.ScalarObject)),
     tslib_1.__param(2, (0, type_graphql_1.Ctx)()),
     tslib_1.__param(3, (0, type_graphql_1.Arg)('start', { nullable: true })),
+    tslib_1.__param(4, (0, type_graphql_1.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.' })),
     tslib_1.__metadata("design:type", Function),
-    tslib_1.__metadata("design:paramtypes", [String, Object, Object, Boolean]),
+    tslib_1.__metadata("design:paramtypes", [String, Object, Object, Boolean, String]),
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinReferenceResolver.prototype, "createFromTemplate", null);
 tslib_1.__decorate([
@@ -376,6 +638,7 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:returntype", Array)
 ], TwinReferenceResolver.prototype, "referenceAdapters", null);
 tslib_1.__decorate([
+    (0, type_graphql_1.Directive)('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)'),
     (0, type_graphql_1.Mutation)(returns => shell_1.ScalarObject, { description: 'Create or update a tenant-scoped twin reference (persisted).' }),
     tslib_1.__param(0, (0, type_graphql_1.Arg)('source')),
     tslib_1.__param(1, (0, type_graphql_1.Arg)('patch', type => shell_1.ScalarObject)),
@@ -385,6 +648,7 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinReferenceResolver.prototype, "saveTwinReference", null);
 tslib_1.__decorate([
+    (0, type_graphql_1.Directive)('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)'),
     (0, type_graphql_1.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).' }),
     tslib_1.__param(0, (0, type_graphql_1.Arg)('source')),
     tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
@@ -394,6 +658,7 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinReferenceResolver.prototype, "deleteTwinReference", null);
 tslib_1.__decorate([
+    (0, type_graphql_1.Directive)('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)'),
     (0, type_graphql_1.Mutation)(returns => shell_1.ScalarObject, { description: 'Test a reference connection via its adapter; updates status.' }),
     tslib_1.__param(0, (0, type_graphql_1.Arg)('source')),
     tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
@@ -402,7 +667,7 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinReferenceResolver.prototype, "testReferenceConnection", null);
 tslib_1.__decorate([
-    (0, type_graphql_1.Query)(returns => [shell_1.ScalarObject], { description: 'Discover sites/factories exposed by a reference (adapter.discoverSites) — for twin-creation site selection.' }),
+    (0, type_graphql_1.Query)(returns => shell_1.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.' }),
     tslib_1.__param(0, (0, type_graphql_1.Arg)('source')),
     tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
     tslib_1.__metadata("design:type", Function),
@@ -410,14 +675,16 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinReferenceResolver.prototype, "discoverReferenceSites", null);
 tslib_1.__decorate([
-    (0, type_graphql_1.Mutation)(returns => shell_1.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.' }),
+    (0, type_graphql_1.Directive)('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)'),
+    (0, type_graphql_1.Mutation)(returns => shell_1.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.' }),
     tslib_1.__param(0, (0, type_graphql_1.Arg)('source')),
     tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
     tslib_1.__param(2, (0, type_graphql_1.Arg)('siteIds', type => [String], { nullable: true })),
     tslib_1.__param(3, (0, type_graphql_1.Arg)('start', { nullable: true })),
     tslib_1.__param(4, (0, type_graphql_1.Arg)('live', { nullable: true })),
+    tslib_1.__param(5, (0, type_graphql_1.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.' })),
     tslib_1.__metadata("design:type", Function),
-    tslib_1.__metadata("design:paramtypes", [String, Object, Array, Boolean, Boolean]),
+    tslib_1.__metadata("design:paramtypes", [String, Object, Array, Boolean, Boolean, String]),
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinReferenceResolver.prototype, "importTwinReference", null);
 exports.TwinReferenceResolver = TwinReferenceResolver = tslib_1.__decorate([