@things-factory/headless-twin 10.0.11 → 10.0.13

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

@@ -2,9 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TwinReferenceResolver = void 0;
 const tslib_1 = require("tslib");
-const type_graphql_1 = require("type-graphql");
 const shell_1 = require("@things-factory/shell");
+const reference_progress_js_1 = require("./reference-progress.js");
+const reference_assessment_js_1 = require("./reference-assessment.js");
+const type_graphql_1 = require("type-graphql");
+const shell_2 = require("@things-factory/shell");
 const index_js_1 = require("../../engine/index.js");
+const restart_policy_js_1 = require("../../engine/restart-policy.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");
@@ -84,7 +88,7 @@ async function resolveSiteEquipmentKnobs(knobs, effective, domainId, spaceId) {
             continue;
         }
         if (ids === undefined) {
-            const rows = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).find({ where: { domain: { id: domainId }, spaceId } });
+            const rows = await (0, shell_2.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 ?? {})) {
@@ -106,7 +110,7 @@ let TwinReferenceResolver = class TwinReferenceResolver {
         const domainId = context.state.domain.id;
         const out = [];
         for (const m of (0, reference_registry_js_1.listReferences)()) {
-            const reg = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId: m.source } });
+            const reg = await (0, shell_2.getRepository)(twin_instance_js_1.TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId: m.source } });
             out.push({
                 source: m.source,
                 system: m.system,
@@ -121,7 +125,7 @@ let TwinReferenceResolver = class TwinReferenceResolver {
         return out;
     }
     /** 소스를 인제스트 → 공간 + 인스턴스 생성(provision). start 면 기동까지. */
-    async importFromReference(source, context, start) {
+    async importFromReference(source, restartPolicy, context, start) {
         const master = (0, reference_registry_js_1.getReference)(source);
         if (!master)
             return { ok: false, error: `unknown reference source: ${source}` };
@@ -130,7 +134,7 @@ let TwinReferenceResolver = class TwinReferenceResolver {
             /* 어디서 왔는지 남긴다 — 이것이 없으면 이 트윈은 두 번 다시 읽을 수 없다.
                이 경로는 **메모리에 등록된 마스터 하나**를 그대로 쓰므로 사이트 서술자가 없다(사이트 정체를
                적을 것이 없다). 다시 읽기도 같은 등록본을 집으므로 사이트를 찾을 필요가 없다. */
-            const res = await index_js_1.TwinEngine.ingestMaster(domainId, { ...master, origin: { kind: 'reference', source } }, undefined, context.state.user);
+            const res = await index_js_1.TwinEngine.ingestMaster(domainId, { ...master, origin: { kind: 'reference', source } }, (0, restart_policy_js_1.readRestartPolicy)(restartPolicy, 'importFromReference'), 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 };
@@ -159,7 +163,7 @@ let TwinReferenceResolver = class TwinReferenceResolver {
      */
     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 } });
+        const inst = await (0, shell_2.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;
@@ -168,23 +172,81 @@ let TwinReferenceResolver = class TwinReferenceResolver {
                 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.`
             };
+        /*
+         * 진행을 알리는 통로 — 만들 때와 **같은 것**이다. 레퍼런스에서 온 트윈만 알린다(템플릿에서 온
+         * 트윈은 원본을 읽지 않으므로 알릴 단계가 없다).
+         *
+         * 분모는 그 어댑터가 선언한 단계 수다(`masterSteps`) + 호스트 단계. 선언하지 않은 어댑터는
+         * `total` 이 없고, 그때 화면은 퍼센트를 만들지 않는다 — 모르는 진행률을 지어내지 않는다.
+         */
+        const progressSource = origin.kind === 'reference' ? origin.source : undefined;
+        const refRow = progressSource
+            ? await (0, shell_2.getRepository)(twin_reference_js_1.TwinReference).findOne({ where: { domain: { id: domainId }, source: progressSource } })
+            : null;
+        const adapterForSteps = refRow ? (0, reference_adapter_js_1.getAdapter)(refRow.adapterType) : undefined;
+        const declaredSteps = adapterForSteps?.masterSteps?.length;
+        const stepTotal = declaredSteps === undefined ? undefined : declaredSteps + reference_progress_js_1.HOST_STEPS.length;
+        const siteId = origin.siteId ?? instanceId;
+        let lastDone = 0;
+        let lastStep = (adapterForSteps?.masterSteps?.[0] ?? 'provision');
+        const emit = (p) => {
+            if (!progressSource)
+                return;
+            lastDone = p.done;
+            lastStep = p.step;
+            shell_1.pubsub.publish('twin-reference-progress', {
+                twinReferenceProgress: { ...p, siteId, siteIndex: 0, siteCount: 1, total: p.total ?? stepTotal, source: progressSource }
+            });
+        };
         try {
-            const master = await this.masterFromOrigin(domainId, origin, instanceId);
+            const master = await this.masterFromOrigin(domainId, origin, instanceId, st => emit({ step: st.key, done: st.done, total: stepTotal, detail: st.detail }));
+            emit({ step: 'provision', done: declaredSteps ?? 0, total: stepTotal });
             /*
              * **어느 현장의 트윈이었나를 지킨다** — 다시 읽기는 구조만 새로 그리는 일이고, 현장 소속은 그때
              * 사람이 고른 것이다. 기억이 없는 옛 트윈은 **지금 있는 현장**을 그대로 쓴다(빈손으로 두면 템플릿
              * 기본 공간으로 옮겨 간다 — 조용히 현장을 떠나고 그 현장의 값도 잃는다).
              */
             const keepSpace = origin.spaceId || inst.spaceId;
-            const res = await index_js_1.TwinEngine.ingestMaster(domainId, master, keepSpace ? { spaceId: keepSpace } : undefined, context.state.user);
+            /* 다시 읽기는 **구조만** 새로 그린다 — 재기동 정책은 그 트윈의 선언이므로 그대로 지킨다. */
+            const res = await index_js_1.TwinEngine.ingestMaster(domainId, master, (0, restart_policy_js_1.readRestartPolicy)(inst.restartPolicy, `resync of twin "${instanceId}"`), keepSpace ? { spaceId: keepSpace } : undefined, context.state.user);
+            emit({ step: 'start', done: (declaredSteps ?? 0) + 1, total: stepTotal });
+            /*
+             * **총평도 새로 남긴다.** 다시 읽었는데 총평이 옛것이면 화면이 지난 읽기를 현재로 보여 준다 —
+             * 그 표를 보고 사람이 원본을 고치러 간다.
+             */
+            if (refRow && progressSource) {
+                const prevSpec = refRow.scopeSpec ?? {};
+                await (0, shell_2.getRepository)(twin_reference_js_1.TwinReference).update({ id: refRow.id }, {
+                    scopeSpec: { ...prevSpec, assessments: { ...(prevSpec.assessments ?? {}), [siteId]: (0, reference_assessment_js_1.assessMaster)(master, siteId) } }
+                });
+            }
             return { ok: true, instanceId: res.instanceId, spaceId: res.spaceId, warnings: res.warnings };
         }
         catch (e) {
+            /* 막힌 자리를 그대로 알린다 — 「끝낸 수」의 다음 단계다(만들 때와 같은 규칙). */
+            emit({
+                step: (adapterForSteps?.masterSteps?.[lastDone] ?? lastStep),
+                done: lastDone,
+                total: stepTotal,
+                failed: true,
+                error: e?.message ?? String(e)
+            });
             return refusal(context, e, 'resync failed');
         }
     }
     /** 기억해 둔 원천에서 마스터를 다시 얻는다 — 어댑터든 템플릿이든 이 한 곳에서 갈린다. */
-    async masterFromOrigin(domainId, origin, instanceId) {
+    async masterFromOrigin(domainId, origin, instanceId, 
+    /*
+     * **다시 읽기도 진행을 보여야 한다** (2026-08-22).
+     *
+     * 만들 때는 8단계가 화면에 흐르는데 다시 읽을 때는 아무것도 없었다 — 사용자가 버튼을 누르고
+     * 「진행되고 있는지 확인할 수가 없다」고 했다. 실제로 chef 는 원본 읽기가 14~21초이고 그 사이
+     * 화면에 아무 변화가 없다.
+     *
+     * 통로는 만들 때와 **같은 것**이다(`twin-reference-progress`). 화면도 같은 표시를 쓴다 —
+     * 두 벌을 만들면 한쪽만 고쳐지고 사람은 같은 일이 다르게 보이는 것을 결함으로 읽는다.
+     */
+    onStep) {
         if (origin.kind === 'template') {
             const tpl = (0, template_registry_js_1.getTemplate)(origin.templateId);
             if (!tpl)
@@ -200,7 +262,7 @@ let TwinReferenceResolver = class TwinReferenceResolver {
         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 } });
+        const ref = await (0, shell_2.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);
@@ -223,7 +285,7 @@ let TwinReferenceResolver = class TwinReferenceResolver {
          */
         const picked = (0, reference_master_js_1.pickOriginSite)(sites, origin);
         if (picked.site)
-            return { ...(await adapter.fetchMaster(cfg, picked.site)), origin };
+            return { ...(await adapter.fetchMaster(cfg, picked.site, onStep)), 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) {
@@ -239,7 +301,7 @@ let TwinReferenceResolver = class TwinReferenceResolver {
         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, spaceId) {
+    async createFromTemplate(templateId, params, restartPolicy, context, start, spaceId) {
         const tpl = (0, template_registry_js_1.getTemplate)(templateId);
         if (!tpl)
             return { ok: false, error: `unknown template: ${templateId}` };
@@ -270,7 +332,7 @@ let TwinReferenceResolver = class TwinReferenceResolver {
             master.origin = { kind: 'template', templateId, params: effective, ...(spaceId ? { spaceId } : {}) };
             /* 공간 선택은 템플릿을 거치지 않는다 — 템플릿마다 이 노브를 알고 있어야 한다면 새 템플릿이
                조용히 무시하게 된다. 합성된 마스터에 한 곳에서 얹는다(레퍼런스 인제스트와 같은 경로). */
-            const res = await index_js_1.TwinEngine.ingestMaster(domainId, master, { spaceId }, context.state.user);
+            const res = await index_js_1.TwinEngine.ingestMaster(domainId, master, (0, restart_policy_js_1.readRestartPolicy)(restartPolicy, `createFromTemplate("${templateId}")`), { spaceId }, context.state.user);
             if (start !== false) {
                 await index_js_1.TwinEngine.startFromRegistry(domainId, res.instanceId);
                 if (scenario) {
@@ -297,9 +359,16 @@ let TwinReferenceResolver = class TwinReferenceResolver {
      */
     async twinReferences(context) {
         const domainId = context.state.domain.id;
-        const rows = await (0, shell_1.getRepository)(twin_reference_js_1.TwinReference).find({ where: { domain: { id: domainId } } });
-        // provenance 라이브 대조 — 지워진 트윈은 producedCount 에서 자동 제외(상태 동기의 lazy 방식).
-        const liveIds = new Set((await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).find({ where: { domain: { id: domainId } } })).map(i => i.instanceId));
+        const rows = await (0, shell_2.getRepository)(twin_reference_js_1.TwinReference).find({ where: { domain: { id: domainId } } });
+        /*
+         * provenance 라이브 대조 — 지워진 트윈은 producedCount 에서 자동 제외(상태 동기의 lazy 방식).
+         *
+         * **id 만 읽는다** (2026-08-21). 예전에는 인스턴스 행 전체를 읽었고, 그 행에는 **모델 JSON** 이
+         * 들어 있다(자리 수백 개 + 발자국 좌표). 그래서 이 목록을 여는 데 수 메가바이트를 읽고 파싱했고,
+         * 화면은 그동안 「아직 연결된 시스템이 없습니다」를 보이고 있었다 — 사용자에게는 「없다」는 답으로
+         * 읽힌다. 여기서 필요한 것은 살아 있는 id 집합 하나다.
+         */
+        const liveIds = new Set((await (0, shell_2.getRepository)(twin_instance_js_1.TwinInstance).find({ where: { domain: { id: domainId } }, select: ['instanceId'] })).map(i => i.instanceId));
         return rows.map(r => {
             const produced = (r.scopeSpec?.produced ?? []).filter(p => liveIds.has(p.instanceId));
             return {
@@ -319,8 +388,8 @@ let TwinReferenceResolver = class TwinReferenceResolver {
      */
     async twinConnections(context) {
         const domainId = context.state.domain.id;
-        const rows = await (0, shell_1.getRepository)(twin_reference_js_1.TwinReference).find({ where: { domain: { id: domainId } } });
-        const liveIds = new Set((await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).find({ where: { domain: { id: domainId } } })).map(i => i.instanceId));
+        const rows = await (0, shell_2.getRepository)(twin_reference_js_1.TwinReference).find({ where: { domain: { id: domainId } } });
+        const liveIds = new Set((await (0, shell_2.getRepository)(twin_instance_js_1.TwinInstance).find({ where: { domain: { id: domainId } } })).map(i => i.instanceId));
         const groups = new Map();
         for (const r of rows) {
             const connectorType = r.scopeSpec?.connectorType ?? r.adapterType;
@@ -340,11 +409,11 @@ let TwinReferenceResolver = class TwinReferenceResolver {
     /** 한 Connection 그룹 노드 상세 — 그 아래 생성된 트윈 인스턴스(라이브 대조·상태·기동여부). */
     async twinConnection(source, context) {
         const domainId = context.state.domain.id;
-        const r = await (0, shell_1.getRepository)(twin_reference_js_1.TwinReference).findOne({ where: { domain: { id: domainId }, source } });
+        const r = await (0, shell_2.getRepository)(twin_reference_js_1.TwinReference).findOne({ where: { domain: { id: domainId }, source } });
         if (!r)
             return null;
         const produced = (r.scopeSpec?.produced ?? []);
-        const instMap = new Map((await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).find({ where: { domain: { id: domainId } } })).map(i => [i.instanceId, i]));
+        const instMap = new Map((await (0, shell_2.getRepository)(twin_instance_js_1.TwinInstance).find({ where: { domain: { id: domainId } } })).map(i => [i.instanceId, i]));
         const instances = produced
             .filter(p => instMap.has(p.instanceId))
             .map(p => {
@@ -364,24 +433,44 @@ let TwinReferenceResolver = class TwinReferenceResolver {
     }
     /** 단건 상세(뷰/편집) — connectionConfig 포함, 어댑터 스키마의 secret 필드는 마스킹(있으면 '••••••'). */
     async twinReference(source, context) {
-        const r = await (0, shell_1.getRepository)(twin_reference_js_1.TwinReference).findOne({ where: { domain: { id: context.state.domain.id }, source } });
+        const r = await (0, shell_2.getRepository)(twin_reference_js_1.TwinReference).findOne({ where: { domain: { id: context.state.domain.id }, source } });
         if (!r)
             return null;
         const secretKeys = new Set(((0, reference_adapter_js_1.getAdapter)(r.adapterType)?.meta?.configSchema ?? []).filter(f => f.secret).map(f => f.key));
         const cfg = {};
         for (const [k, v] of Object.entries(r.connectionConfig ?? {}))
             cfg[k] = secretKeys.has(k) ? (v ? '••••••' : '') : v;
+        /*
+         * **이 연결이 만든 트윈 id 를 함께 낸다.** 상세 화면이 「이 연결이 잘 동기화되고 있나」를 물으려면
+         * 어느 트윈을 물어야 하는지 알아야 한다. 예전에는 개수(`producedCount`)만 있어서 화면이 id 를
+         * 알 방법이 없었다.
+         */
+        const producedInstanceIds = [
+            ...new Set((r.scopeSpec?.produced ?? [])
+                .map((p) => p?.instanceId)
+                .filter((x) => typeof x === 'string' && !!x))
+        ];
         return {
             source: r.source, system: r.system, siteName: r.siteName, description: r.description,
-            adapterType: r.adapterType, connectionConfig: cfg, status: r.status, lastSyncedAt: r.lastSyncedAt, lastError: r.lastError
+            adapterType: r.adapterType, connectionConfig: cfg, status: r.status, lastSyncedAt: r.lastSyncedAt, lastError: r.lastError,
+            producedInstanceIds
         };
     }
     referenceAdapters() {
-        return (0, reference_adapter_js_1.listAdapters)().map(a => ({ type: a.type, ...(a.meta ?? {}) }));
+        /*
+         * **능력을 함께 낸다** (2026-08-21).
+         *
+         * `capabilities` 는 어댑터 뿌리에 있고 `meta` 에는 없었다. 그래서 연결 화면이 「이 원본이 라이브를
+         * 낼 수 있나」를 알 수 없었고, 트윈을 만들 때 `live` 를 말하지 못해 **재기동 정책이 없다고 거절**됐다
+         * (실 연동에서 그것에 막혔다 — 미러는 정의상 `resync` 이므로 `live` 하나로 정해진다).
+         *
+         * 화면이 그 사실을 알아야 정책을 사람에게 물을지 스스로 정할지 가를 수 있다.
+         */
+        return (0, reference_adapter_js_1.listAdapters)().map(a => ({ type: a.type, ...(a.meta ?? {}), capabilities: a.capabilities ?? [] }));
     }
     async saveTwinReference(source, patch, context) {
         const domainId = context.state.domain.id;
-        const repo = (0, shell_1.getRepository)(twin_reference_js_1.TwinReference);
+        const repo = (0, shell_2.getRepository)(twin_reference_js_1.TwinReference);
         const existing = await repo.findOne({ where: { domain: { id: domainId }, source } });
         const saved = await repo.save(repo.create({
             ...(existing ?? {}),
@@ -404,7 +493,7 @@ let TwinReferenceResolver = class TwinReferenceResolver {
     /** 연결 해제 — removeTwins=true 면 이 레퍼런스가 만든 트윈(provenance)도 함께 제거(라이프사이클 연쇄). 기본은 트윈 보존(분리). */
     async deleteTwinReference(source, context, removeTwins) {
         const domainId = context.state.domain.id;
-        const repo = (0, shell_1.getRepository)(twin_reference_js_1.TwinReference);
+        const repo = (0, shell_2.getRepository)(twin_reference_js_1.TwinReference);
         const ref = await repo.findOne({ where: { domain: { id: domainId }, source } });
         if (removeTwins && ref) {
             for (const p of (ref.scopeSpec?.produced ?? [])) {
@@ -420,7 +509,7 @@ let TwinReferenceResolver = class TwinReferenceResolver {
         return true;
     }
     async testReferenceConnection(source, context) {
-        const repo = (0, shell_1.getRepository)(twin_reference_js_1.TwinReference);
+        const repo = (0, shell_2.getRepository)(twin_reference_js_1.TwinReference);
         const ref = await repo.findOne({ where: { domain: { id: context.state.domain.id }, source } });
         if (!ref)
             return { ok: false, error: `unknown reference: ${source}` };
@@ -448,7 +537,7 @@ let TwinReferenceResolver = class TwinReferenceResolver {
          * 연결에서 가장 자주 막히는 자리인데 자격이 틀렸는지 주소가 틀렸는지 알 수 없었다.
          * 판정과 문장 형태는 `discovery-result`(순수)가 갖는다.
          */
-        const ref = await (0, shell_1.getRepository)(twin_reference_js_1.TwinReference).findOne({ where: { domain: { id: context.state.domain.id }, source } });
+        const ref = await (0, shell_2.getRepository)(twin_reference_js_1.TwinReference).findOne({ where: { domain: { id: context.state.domain.id }, source } });
         if (!ref)
             return (0, discovery_result_js_1.failed)((0, discovery_result_js_1.referenceNotFound)(source));
         const adapter = (0, reference_adapter_js_1.getAdapter)(ref.adapterType);
@@ -482,9 +571,9 @@ let TwinReferenceResolver = class TwinReferenceResolver {
      * 판정은 그 순수 모듈이 갖는다: 없는 공간은 거절(`resolveIngestSpace`), 사이트 여럿을 한 공간에
      * 넣는 것도 거절(`refuseImportSpace`) — 서로 다른 현장이 조용히 합쳐지는 것을 막는다.
      */
-    async importTwinReference(source, context, siteIds, start, live, spaceId) {
+    async importTwinReference(source, context, siteIds, start, live, spaceId, restartPolicy) {
         const domainId = context.state.domain.id;
-        const repo = (0, shell_1.getRepository)(twin_reference_js_1.TwinReference);
+        const repo = (0, shell_2.getRepository)(twin_reference_js_1.TwinReference);
         const ref = await repo.findOne({ where: { domain: { id: domainId }, source } });
         if (!ref)
             return { ok: false, error: `unknown reference: ${source}` };
@@ -502,15 +591,74 @@ let TwinReferenceResolver = class TwinReferenceResolver {
                 return { ok: false, error: refusal.message, errorCode: refusal.code, errorParams: refusal.params };
             const instances = [];
             const failed = [];
-            for (const site of sites) {
+            /*
+             * **진행을 구독으로 흘린다** (2026-08-21).
+             *
+             * 마스터 읽기는 원본에 여러 질의를 보내는 긴 작업이고, 화면은 그 사이 아무것도 알 수 없었다.
+             * 단계를 아는 것은 어댑터뿐이므로 어댑터가 말하고(표준 낱말), 호스트가 자기 두 단계(생성·기동)를
+             * 더해 흘린다.
+             *
+             * **분모는 어댑터가 선언한 것**이다(`masterSteps`). 선언하지 않은 어댑터는 `total` 이 없고, 그때
+             * 화면은 퍼센트를 만들지 않는다 — 모르는 진행률을 지어내지 않는다.
+             */
+            const declared = adapter.masterSteps?.length;
+            const stepTotal = declared === undefined ? undefined : declared + reference_progress_js_1.HOST_STEPS.length;
+            const emit = (p) => shell_1.pubsub.publish('twin-reference-progress', {
+                twinReferenceProgress: { ...p, siteCount: sites.length, total: p.total ?? stepTotal, source }
+            });
+            /*
+             * **읽은 뒤의 총평을 사이트마다 남긴다** (2026-08-22).
+             *
+             * 총평은 읽는 순간에만 있었다 — 대화상자를 닫으면 사라지고, 다시 보려면 같은 읽기를 또 해야 했다.
+             * 그런데 사람이 그것을 묻는 자리는 「모델 살펴보기」다(트윈을 보다가 「이건 왜 비었나」를 묻는다).
+             * 그래서 레퍼런스 행에 남겨 그 화면이 언제든 읽게 한다.
+             *
+             * 사실만 담는다(`assessMaster`) — 문장은 화면이 만들고, 더 알고 싶을 때 AI 가 이 사실만 근거로
+             * 서술한다. 다시 읽으면 그 사이트의 총평이 새것으로 바뀐다(지난 읽기의 총평을 현재로 보이게
+             * 두지 않는다).
+             */
+            const assessments = {};
+            for (const [siteIndex, site] of sites.entries()) {
+                /*
+                 * **실패를 실제로 막힌 단계에 적는다** (2026-08-22).
+                 *
+                 * 예전에는 실패를 무조건 `provision` 으로 적었다. 그래서 원본을 읽다 끊긴 것도 화면에는
+                 * 「트윈 생성에서 실패」로 떴다 — 사람이 원인을 엉뚱한 자리에서 찾는다(실제로 그렇게 됐다).
+                 *
+                 * 규약이 답을 준다: `done` 은 **끝낸 단계 수**다(`ReferenceProgress.done`). 그러면 지금 막힌 것은
+                 * 그 다음 단계, 즉 `masterSteps[done]` 이다. 그 표를 넘어서면(호스트 단계) 마지막으로 알린 것을 쓴다.
+                 *
+                 * 이 규칙은 두 가지 보고 방식에 함께 맞는다 — 단계 **시작**에 알리는 어댑터(`done` 이 아직 0)와
+                 * 단계 **완료**에 알리는 어댑터(`done` 이 1 늘어난다) 모두 「끝낸 수」만 지키면 된다.
+                 */
+                let lastDone = 0;
+                let lastStep = (adapter.masterSteps?.[0] ?? 'provision');
+                const track = (p) => {
+                    lastDone = p.done;
+                    lastStep = p.step;
+                    emit(p);
+                };
                 try {
-                    const master = await adapter.fetchMaster(cfg, site);
+                    const master = await adapter.fetchMaster(cfg, site, st => track({ siteId: site.siteId, siteIndex, step: st.key, done: st.done, total: stepTotal, detail: st.detail }));
                     /* 어느 레퍼런스의 **어느 사이트**에서 왔는지 남긴다 — 다시 읽기가 같은 어댑터·같은 사이트로 돌아오려면
                        사이트 정체가 있어야 한다(`source` 는 참조 이름이라 사이트 전부에 같다). */
-                    const res = await index_js_1.TwinEngine.ingestMaster(domainId, { ...master, origin: { kind: 'reference', source, siteId: site.siteId, ...(spaceId ? { spaceId } : {}) } }, { spaceId }, context.state.user);
+                    /*
+                     * 정책은 **선언이거나 의도에서 곧바로 따라오는 것**이다: `live=true` 는 미러를 띄우겠다는 뜻이고
+                     * 미러는 정의상 `resync` 다(외부가 진실이므로 우리 과거를 이어 붙이지 않는다). 시뮬로 띄우려면
+                     * 스스로 선언해야 한다 — 그 자리에서 우리가 고르면 재기동마다 이력을 지우는 트윈이 조용히 생긴다.
+                     */
+                    assessments[site.siteId] = (0, reference_assessment_js_1.assessMaster)(master, site.siteId);
+                    const policy = (0, restart_policy_js_1.readRestartPolicy)(restartPolicy ?? (live ? 'resync' : undefined), `importTwinReference("${source}")`);
+                    track({ siteId: site.siteId, siteIndex, step: 'provision', done: declared ?? 0, total: stepTotal });
+                    const res = await index_js_1.TwinEngine.ingestMaster(domainId, { ...master, origin: { kind: 'reference', source, siteId: site.siteId, ...(spaceId ? { spaceId } : {}) } }, policy, { spaceId }, context.state.user);
+                    track({ siteId: site.siteId, siteIndex, step: 'start', done: (declared ?? 0) + 1, total: stepTotal });
                     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;
+                        /* 읽기 커서를 저장할 자리를 함께 넘긴다 — 레퍼런스의 이름은 호스트가 붙이는 것이고
+                           커넥터는 그것을 알 수 없다(§`startReferenceLiveFeed`). */
+                        const wentLive = live
+                            ? await (0, reference_live_js_1.startReferenceLiveFeed)(domainId, ref.adapterType, cfg, site, res.instanceId, ref.source)
+                            : false;
                         if (!wentLive)
                             await index_js_1.TwinEngine.startFromRegistry(domainId, res.instanceId);
                         instances.push({ siteId: site.siteId, instanceId: res.instanceId, spaceId: res.spaceId, mode: wentLive ? 'live' : 'sim', warnings: res.warnings });
@@ -520,6 +668,12 @@ let TwinReferenceResolver = class TwinReferenceResolver {
                     }
                 }
                 catch (e) {
+                    /*
+                     * **실패한 단계를 그대로 알린다.** 화면이 진행 표시를 지우지 않고 그 자리를 붉게 두어야
+                     * 사람이 「어디까지 갔는지」를 안다. 막힌 자리는 「끝낸 수」의 다음 단계다(위 주석).
+                     */
+                    const at = (adapter.masterSteps?.[lastDone] ?? lastStep);
+                    emit({ siteId: site.siteId, siteIndex, step: at, done: lastDone, total: stepTotal, failed: true, error: e?.message ?? String(e) });
                     failed.push({ siteId: site.siteId, error: e?.message ?? 'failed' });
                 }
             }
@@ -529,6 +683,10 @@ let TwinReferenceResolver = class TwinReferenceResolver {
             await repo.update({ id: ref.id }, {
                 status: 'connected',
                 lastSyncedAt: new Date().toISOString(),
+                /* 못 옮긴 값을 **세어 남긴다**. 아무 인스턴스도 보고하지 않았으면 `null` — 「없었다」로 위장하지 않는다. */
+                lastWarningCount: instances.some((i) => Array.isArray(i.warnings))
+                    ? instances.reduce((n, i) => n + (Array.isArray(i.warnings) ? i.warnings.length : 0), 0)
+                    : null,
                 /*
                  * **영어 canonical 로 남긴다.** 이 값은 DB 에 저장되고 연결 화면이 그대로 뿌린다 — 예전에는
                  * 한글 산문(`N개 사이트 실패`)이라 다섯 언어 화면에 한글이 새어 나갔다. 어댑터가 주는 사유도
@@ -536,7 +694,24 @@ let TwinReferenceResolver = class TwinReferenceResolver {
                  * 어느 사이트가 왜 실패했는지는 `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] }
+                /*
+                 * ── 실패 사유를 **남긴다** (2026-08-21) ────────────────────────────────
+                 *
+                 * 사유는 대화상자에만 있었다. 닫으면 사라지고, 다시 보려면 같은 실패를 다시 만들어야 했다 —
+                 * 실제로 「승화푸드」 연결이 그 상태였다(요약 한 줄만 남고 원인은 어디에도 없었다).
+                 *
+                 * `scopeSpec` 은 이미 이 레퍼런스의 부속 사실을 담는 자리이므로(`produced`) 스키마를 늘리지 않고
+                 * 여기 적는다. 성공한 회차에는 **비운다** — 지나간 실패를 현재 상태처럼 보이게 두지 않는다.
+                 */
+                scopeSpec: {
+                    ...(ref.scopeSpec ?? {}),
+                    produced: [...prev, ...producedNew],
+                    /* 이번에 읽은 사이트의 총평만 갈아 끼운다 — 읽지 않은 사이트의 것은 그대로 둔다. */
+                    assessments: { ...((ref.scopeSpec ?? {}).assessments ?? {}), ...assessments },
+                    ...(failed.length
+                        ? { lastFailures: failed.map((f) => ({ siteId: f.siteId, error: f.error, at: new Date().toISOString() })) }
+                        : { lastFailures: [] })
+                }
             });
             return { ok: instances.length > 0, instances, failed };
         }
@@ -549,7 +724,7 @@ let TwinReferenceResolver = class TwinReferenceResolver {
 };
 exports.TwinReferenceResolver = TwinReferenceResolver;
 tslib_1.__decorate([
-    (0, type_graphql_1.Query)(returns => [shell_1.ScalarObject], { description: 'List registered reference sources (virtual or real adapters) available to ingest.' }),
+    (0, type_graphql_1.Query)(returns => [shell_2.ScalarObject], { description: 'List registered reference sources (virtual or real adapters) available to ingest.' }),
     tslib_1.__param(0, (0, type_graphql_1.Ctx)()),
     tslib_1.__metadata("design:type", Function),
     tslib_1.__metadata("design:paramtypes", [Object]),
@@ -557,17 +732,20 @@ tslib_1.__decorate([
 ], 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.' }),
+    (0, type_graphql_1.Mutation)(returns => shell_2.ScalarObject, {
+        description: "Ingest a registered reference source into a twin (space + instance). Optionally start it. restartPolicy declares how the new twin treats its own past on reboot: 'resync' (read the source again) | 'resume' (continue its journal) | 'reset' (wipe and replay from the seed). It has no default — a twin cannot exist without the declaration."
+    }),
     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)('start', { nullable: true })),
+    tslib_1.__param(1, (0, type_graphql_1.Arg)('restartPolicy')),
+    tslib_1.__param(2, (0, type_graphql_1.Ctx)()),
+    tslib_1.__param(3, (0, type_graphql_1.Arg)('start', { nullable: true })),
     tslib_1.__metadata("design:type", Function),
-    tslib_1.__metadata("design:paramtypes", [String, Object, Boolean]),
+    tslib_1.__metadata("design:paramtypes", [String, 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, {
+    (0, type_graphql_1.Mutation)(returns => shell_2.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')),
@@ -577,7 +755,7 @@ tslib_1.__decorate([
     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.' }),
+    (0, type_graphql_1.Query)(returns => [shell_2.ScalarObject], { description: 'List registered twin templates (parameterized archetypes) with their knob schema.' }),
     tslib_1.__param(0, (0, type_graphql_1.Ctx)()),
     tslib_1.__metadata("design:type", Function),
     tslib_1.__metadata("design:paramtypes", [Object]),
@@ -585,18 +763,21 @@ tslib_1.__decorate([
 ], 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}.' }),
+    (0, type_graphql_1.Mutation)(returns => shell_2.ScalarObject, {
+        description: "Instantiate a twin template with params → synthetic master → ingest (+start+scenario). restartPolicy declares how the new twin treats its own past on reboot ('resync' | 'resume' | 'reset') — there is no default. 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.__param(1, (0, type_graphql_1.Arg)('params', type => shell_2.ScalarObject)),
+    tslib_1.__param(2, (0, type_graphql_1.Arg)('restartPolicy')),
+    tslib_1.__param(3, (0, type_graphql_1.Ctx)()),
+    tslib_1.__param(4, (0, type_graphql_1.Arg)('start', { 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). Omit to create its own space.' })),
     tslib_1.__metadata("design:type", Function),
-    tslib_1.__metadata("design:paramtypes", [String, Object, Object, Boolean, String]),
+    tslib_1.__metadata("design:paramtypes", [String, Object, String, Object, Boolean, String]),
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinReferenceResolver.prototype, "createFromTemplate", null);
 tslib_1.__decorate([
-    (0, type_graphql_1.Query)(returns => [shell_1.ScalarObject], { description: 'List tenant-scoped persisted twin references (adapter-backed).' }),
+    (0, type_graphql_1.Query)(returns => [shell_2.ScalarObject], { description: 'List tenant-scoped persisted twin references (adapter-backed).' }),
     tslib_1.__param(0, (0, type_graphql_1.Ctx)()),
     tslib_1.__metadata("design:type", Function),
     tslib_1.__metadata("design:paramtypes", [Object]),
@@ -609,14 +790,14 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:returntype", Array)
 ], TwinReferenceResolver.prototype, "referenceAdapterTypes", null);
 tslib_1.__decorate([
-    (0, type_graphql_1.Query)(returns => [shell_1.ScalarObject], { description: 'Group integration items 2-tier: connector type ▸ connection ▸ produced twins. (reference-management §2.3)' }),
+    (0, type_graphql_1.Query)(returns => [shell_2.ScalarObject], { description: 'Group integration items 2-tier: connector type ▸ connection ▸ produced twins. (reference-management §2.3)' }),
     tslib_1.__param(0, (0, type_graphql_1.Ctx)()),
     tslib_1.__metadata("design:type", Function),
     tslib_1.__metadata("design:paramtypes", [Object]),
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinReferenceResolver.prototype, "twinConnections", null);
 tslib_1.__decorate([
-    (0, type_graphql_1.Query)(returns => shell_1.ScalarObject, { nullable: true, description: 'One connection grouping location with its produced twin instances (live-checked). (reference-management §2.3)' }),
+    (0, type_graphql_1.Query)(returns => shell_2.ScalarObject, { nullable: true, description: 'One connection grouping location with its produced twin instances (live-checked). (reference-management §2.3)' }),
     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),
@@ -624,7 +805,7 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinReferenceResolver.prototype, "twinConnection", null);
 tslib_1.__decorate([
-    (0, type_graphql_1.Query)(returns => shell_1.ScalarObject, { nullable: true, description: 'Get one tenant-scoped reference with its connection config (secret fields masked) for view/edit.' }),
+    (0, type_graphql_1.Query)(returns => shell_2.ScalarObject, { nullable: true, description: 'Get one tenant-scoped reference with its connection config (secret fields masked) for view/edit.' }),
     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),
@@ -632,16 +813,16 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinReferenceResolver.prototype, "twinReference", null);
 tslib_1.__decorate([
-    (0, type_graphql_1.Query)(returns => [shell_1.ScalarObject], { description: 'List reference connector metadata (label, domain, config schema, availability) for the connect UI.' }),
+    (0, type_graphql_1.Query)(returns => [shell_2.ScalarObject], { description: 'List reference connector metadata (label, domain, config schema, availability, capabilities) for the connect UI.' }),
     tslib_1.__metadata("design:type", Function),
     tslib_1.__metadata("design:paramtypes", []),
     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).' }),
+    (0, type_graphql_1.Mutation)(returns => shell_2.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)),
+    tslib_1.__param(1, (0, type_graphql_1.Arg)('patch', type => shell_2.ScalarObject)),
     tslib_1.__param(2, (0, type_graphql_1.Ctx)()),
     tslib_1.__metadata("design:type", Function),
     tslib_1.__metadata("design:paramtypes", [String, Object, Object]),
@@ -659,7 +840,7 @@ tslib_1.__decorate([
 ], 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.' }),
+    (0, type_graphql_1.Mutation)(returns => shell_2.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)()),
     tslib_1.__metadata("design:type", Function),
@@ -667,7 +848,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. Returns { sites, error? } — an empty list with no error means the system genuinely has none, which is different from a failure.' }),
+    (0, type_graphql_1.Query)(returns => shell_2.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),
@@ -676,15 +857,18 @@ tslib_1.__decorate([
 ], TwinReferenceResolver.prototype, "discoverReferenceSites", 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 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.' }),
+    (0, type_graphql_1.Mutation)(returns => shell_2.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. restartPolicy declares how each new twin treats its own past on reboot ('resync' | 'resume' | 'reset'); omit it and live=true implies 'resync' — a mirror reads the source again — while a simulation must declare 'resume' or 'reset' for itself."
+    }),
     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.__param(6, (0, type_graphql_1.Arg)('restartPolicy', { nullable: true, description: "How each new twin treats its own past on reboot: 'resync' | 'resume' | 'reset'. Required unless live=true (a mirror is 'resync' by definition)." })),
     tslib_1.__metadata("design:type", Function),
-    tslib_1.__metadata("design:paramtypes", [String, Object, Array, Boolean, Boolean, String]),
+    tslib_1.__metadata("design:paramtypes", [String, Object, Array, Boolean, Boolean, String, String]),
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinReferenceResolver.prototype, "importTwinReference", null);
 exports.TwinReferenceResolver = TwinReferenceResolver = tslib_1.__decorate([