@things-factory/headless-twin 10.0.11 → 10.0.13

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

@@ -1,8 +1,12 @@
+import { pubsub } from '@things-factory/shell'
+import { HOST_STEPS, type ReferenceProgress } from './reference-progress.js'
+import { assessMaster } from './reference-assessment.js'
 import { Arg, Ctx, Mutation, Query, Resolver, Directive} from 'type-graphql'
 
 import { ScalarObject, getRepository } from '@things-factory/shell'
 
 import { TwinEngine } from '../../engine/index.js'
+import { readRestartPolicy } from '../../engine/restart-policy.js'
 import { readBoardEquipment } from '@operato/twin-kernel'
 
 import { applyKnobDefaults, filledKnobKeys } from './knob-defaults.js'
@@ -140,9 +144,13 @@ export class TwinReferenceResolver {
 
   /** 소스를 인제스트 → 공간 + 인스턴스 생성(provision). start 면 기동까지. */
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => ScalarObject, { description: 'Ingest a registered reference source into a twin (space + instance). Optionally start it.' })
+  @Mutation(returns => 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."
+  })
   async importFromReference(
     @Arg('source') source: string,
+    @Arg('restartPolicy') restartPolicy: string,
     @Ctx() context: ResolverContext,
     @Arg('start', { nullable: true }) start?: boolean
   ): Promise<any> {
@@ -153,7 +161,13 @@ export class TwinReferenceResolver {
       /* 어디서 왔는지 남긴다 — 이것이 없으면 이 트윈은 두 번 다시 읽을 수 없다.
          이 경로는 **메모리에 등록된 마스터 하나**를 그대로 쓰므로 사이트 서술자가 없다(사이트 정체를
          적을 것이 없다). 다시 읽기도 같은 등록본을 집으므로 사이트를 찾을 필요가 없다. */
-      const res = await TwinEngine.ingestMaster(domainId, { ...master, origin: { kind: 'reference', source } }, undefined, context.state.user)
+      const res = await TwinEngine.ingestMaster(
+        domainId,
+        { ...master, origin: { kind: 'reference', source } },
+        readRestartPolicy(restartPolicy, 'importFromReference'),
+        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) {
@@ -196,23 +210,96 @@ export class TwinReferenceResolver {
         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: string | undefined = origin.kind === 'reference' ? origin.source : undefined
+    const refRow = progressSource
+      ? await getRepository(TwinReference).findOne({ where: { domain: { id: domainId }, source: progressSource } })
+      : null
+    const adapterForSteps = refRow ? getAdapter(refRow.adapterType) : undefined
+    const declaredSteps = adapterForSteps?.masterSteps?.length
+    const stepTotal = declaredSteps === undefined ? undefined : declaredSteps + HOST_STEPS.length
+    const siteId = origin.siteId ?? instanceId
+    let lastDone = 0
+    let lastStep: ReferenceProgress['step'] = (adapterForSteps?.masterSteps?.[0] ?? 'provision') as ReferenceProgress['step']
+    const emit = (p: Omit<ReferenceProgress, 'siteCount' | 'siteId' | 'siteIndex'>) => {
+      if (!progressSource) return
+      lastDone = p.done
+      lastStep = p.step
+      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 TwinEngine.ingestMaster(domainId, master, keepSpace ? { spaceId: keepSpace } : undefined, context.state.user)
+      /* 다시 읽기는 **구조만** 새로 그린다 — 재기동 정책은 그 트윈의 선언이므로 그대로 지킨다. */
+      const res = await TwinEngine.ingestMaster(
+        domainId,
+        master,
+        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 as any) ?? {}
+        await getRepository(TwinReference).update(
+          { id: refRow.id },
+          {
+            scopeSpec: { ...prevSpec, assessments: { ...(prevSpec.assessments ?? {}), [siteId]: assessMaster(master, siteId) } }
+          } as any
+        )
+      }
       return { ok: true, instanceId: res.instanceId, spaceId: res.spaceId, warnings: res.warnings }
     } catch (e: any) {
+      /* 막힌 자리를 그대로 알린다 — 「끝낸 수」의 다음 단계다(만들 때와 같은 규칙). */
+      emit({
+        step: (adapterForSteps?.masterSteps?.[lastDone] ?? lastStep) as ReferenceProgress['step'],
+        done: lastDone,
+        total: stepTotal,
+        failed: true,
+        error: e?.message ?? String(e)
+      })
       return refusal(context, e, 'resync failed')
     }
   }
 
   /** 기억해 둔 원천에서 마스터를 다시 얻는다 — 어댑터든 템플릿이든 이 한 곳에서 갈린다. */
-  private async masterFromOrigin(domainId: string, origin: any, instanceId: string): Promise<any> {
+  private async masterFromOrigin(
+    domainId: string,
+    origin: any,
+    instanceId: string,
+    /*
+     * **다시 읽기도 진행을 보여야 한다** (2026-08-22).
+     *
+     * 만들 때는 8단계가 화면에 흐르는데 다시 읽을 때는 아무것도 없었다 — 사용자가 버튼을 누르고
+     * 「진행되고 있는지 확인할 수가 없다」고 했다. 실제로 chef 는 원본 읽기가 14~21초이고 그 사이
+     * 화면에 아무 변화가 없다.
+     *
+     * 통로는 만들 때와 **같은 것**이다(`twin-reference-progress`). 화면도 같은 표시를 쓴다 —
+     * 두 벌을 만들면 한쪽만 고쳐지고 사람은 같은 일이 다르게 보이는 것을 결함으로 읽는다.
+     */
+    onStep?: (s: { key: any; done: number; total?: number; detail?: string }) => void
+  ): 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`)
@@ -249,7 +336,7 @@ export class TwinReferenceResolver {
      * 다른 현장의 구조를 이 트윈에 덮는 것은 오류가 아니라 조용히 틀린 공장으로 나타난다.
      */
     const picked = pickOriginSite(sites, origin)
-    if (picked.site) return { ...(await adapter.fetchMaster(cfg, picked.site)), origin }
+    if (picked.site) 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`
@@ -273,10 +360,14 @@ export class TwinReferenceResolver {
 
   /** 템플릿 + 노브 → 합성 마스터 → 인제스트(+기동+시나리오). 레퍼런스 import 와 같은 경로, 원천만 합성. */
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => ScalarObject, { description: 'Instantiate a twin template with params → synthetic master → ingest (+start+scenario). Returns {ok, instanceId, spaceId}.' })
+  @Mutation(returns => 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}."
+  })
   async createFromTemplate(
     @Arg('templateId') templateId: string,
     @Arg('params', type => ScalarObject) params: any,
+    @Arg('restartPolicy') restartPolicy: string,
     @Ctx() context: ResolverContext,
     @Arg('start', { nullable: true }) start?: boolean,
     @Arg('spaceId', { nullable: true, description: 'Existing space to co-locate this twin into (add a lens to a site). Omit to create its own space.' }) spaceId?: string
@@ -310,7 +401,13 @@ export class TwinReferenceResolver {
       master.origin = { kind: 'template', templateId, params: effective, ...(spaceId ? { spaceId } : {}) }
       /* 공간 선택은 템플릿을 거치지 않는다 — 템플릿마다 이 노브를 알고 있어야 한다면 새 템플릿이
          조용히 무시하게 된다. 합성된 마스터에 한 곳에서 얹는다(레퍼런스 인제스트와 같은 경로). */
-      const res = await TwinEngine.ingestMaster(domainId, master, { spaceId }, context.state.user)
+      const res = await TwinEngine.ingestMaster(
+        domainId,
+        master,
+        readRestartPolicy(restartPolicy, `createFromTemplate("${templateId}")`),
+        { spaceId },
+        context.state.user
+      )
       if (start !== false) {
         await TwinEngine.startFromRegistry(domainId, res.instanceId)
         if (scenario) {
@@ -340,8 +437,19 @@ export class TwinReferenceResolver {
   async twinReferences(@Ctx() context: ResolverContext): Promise<any[]> {
     const domainId = context.state.domain.id
     const rows = await getRepository(TwinReference).find({ where: { domain: { id: domainId } } })
-    // provenance 라이브 대조 — 지워진 트윈은 producedCount 에서 자동 제외(상태 동기의 lazy 방식).
-    const liveIds = new Set((await getRepository(TwinInstance).find({ where: { domain: { id: domainId } } })).map(i => i.instanceId))
+    /*
+     * provenance 라이브 대조 — 지워진 트윈은 producedCount 에서 자동 제외(상태 동기의 lazy 방식).
+     *
+     * **id 만 읽는다** (2026-08-21). 예전에는 인스턴스 행 전체를 읽었고, 그 행에는 **모델 JSON** 이
+     * 들어 있다(자리 수백 개 + 발자국 좌표). 그래서 이 목록을 여는 데 수 메가바이트를 읽고 파싱했고,
+     * 화면은 그동안 「아직 연결된 시스템이 없습니다」를 보이고 있었다 — 사용자에게는 「없다」는 답으로
+     * 읽힌다. 여기서 필요한 것은 살아 있는 id 집합 하나다.
+     */
+    const liveIds = new Set(
+      (await getRepository(TwinInstance).find({ where: { domain: { id: domainId } }, select: ['instanceId'] })).map(
+        i => i.instanceId
+      )
+    )
     return rows.map(r => {
       const produced = (((r.scopeSpec as any)?.produced ?? []) as any[]).filter(p => liveIds.has(p.instanceId))
       return {
@@ -417,15 +525,37 @@ export class TwinReferenceResolver {
     const secretKeys = new Set((getAdapter(r.adapterType)?.meta?.configSchema ?? []).filter(f => f.secret).map(f => f.key))
     const cfg: any = {}
     for (const [k, v] of Object.entries((r.connectionConfig as any) ?? {})) cfg[k] = secretKeys.has(k) ? (v ? '••••••' : '') : v
+    /*
+     * **이 연결이 만든 트윈 id 를 함께 낸다.** 상세 화면이 「이 연결이 잘 동기화되고 있나」를 물으려면
+     * 어느 트윈을 물어야 하는지 알아야 한다. 예전에는 개수(`producedCount`)만 있어서 화면이 id 를
+     * 알 방법이 없었다.
+     */
+    const producedInstanceIds = [
+      ...new Set(
+        ((r.scopeSpec as any)?.produced ?? [])
+          .map((p: any) => p?.instanceId)
+          .filter((x: any): x is string => 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
     }
   }
 
-  @Query(returns => [ScalarObject], { description: 'List reference connector metadata (label, domain, config schema, availability) for the connect UI.' })
+  @Query(returns => [ScalarObject], { description: 'List reference connector metadata (label, domain, config schema, availability, capabilities) for the connect UI.' })
   referenceAdapters(): any[] {
-    return listAdapters().map(a => ({ type: a.type, ...(a.meta ?? {}) }))
+    /*
+     * **능력을 함께 낸다** (2026-08-21).
+     *
+     * `capabilities` 는 어댑터 뿌리에 있고 `meta` 에는 없었다. 그래서 연결 화면이 「이 원본이 라이브를
+     * 낼 수 있나」를 알 수 없었고, 트윈을 만들 때 `live` 를 말하지 못해 **재기동 정책이 없다고 거절**됐다
+     * (실 연동에서 그것에 막혔다 — 미러는 정의상 `resync` 이므로 `live` 하나로 정해진다).
+     *
+     * 화면이 그 사실을 알아야 정책을 사람에게 물을지 스스로 정할지 가를 수 있다.
+     */
+    return listAdapters().map(a => ({ type: a.type, ...(a.meta ?? {}), capabilities: a.capabilities ?? [] }))
   }
 
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
@@ -545,14 +675,18 @@ export class TwinReferenceResolver {
    * 넣는 것도 거절(`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. 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.' })
+  @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. 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."
+  })
   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('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
+    @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,
+    @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)." }) restartPolicy?: string
   ): Promise<any> {
     const domainId = context.state.domain.id
     const repo = getRepository(TwinReference)
@@ -569,26 +703,98 @@ export class TwinReferenceResolver {
       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) {
+      /*
+       * **진행을 구독으로 흘린다** (2026-08-21).
+       *
+       * 마스터 읽기는 원본에 여러 질의를 보내는 긴 작업이고, 화면은 그 사이 아무것도 알 수 없었다.
+       * 단계를 아는 것은 어댑터뿐이므로 어댑터가 말하고(표준 낱말), 호스트가 자기 두 단계(생성·기동)를
+       * 더해 흘린다.
+       *
+       * **분모는 어댑터가 선언한 것**이다(`masterSteps`). 선언하지 않은 어댑터는 `total` 이 없고, 그때
+       * 화면은 퍼센트를 만들지 않는다 — 모르는 진행률을 지어내지 않는다.
+       */
+      const declared = adapter.masterSteps?.length
+      const stepTotal = declared === undefined ? undefined : declared + HOST_STEPS.length
+      const emit = (p: Omit<ReferenceProgress, 'siteCount'>) =>
+        pubsub.publish('twin-reference-progress', {
+          twinReferenceProgress: { ...p, siteCount: sites.length, total: p.total ?? stepTotal, source }
+        })
+
+      /*
+       * **읽은 뒤의 총평을 사이트마다 남긴다** (2026-08-22).
+       *
+       * 총평은 읽는 순간에만 있었다 — 대화상자를 닫으면 사라지고, 다시 보려면 같은 읽기를 또 해야 했다.
+       * 그런데 사람이 그것을 묻는 자리는 「모델 살펴보기」다(트윈을 보다가 「이건 왜 비었나」를 묻는다).
+       * 그래서 레퍼런스 행에 남겨 그 화면이 언제든 읽게 한다.
+       *
+       * 사실만 담는다(`assessMaster`) — 문장은 화면이 만들고, 더 알고 싶을 때 AI 가 이 사실만 근거로
+       * 서술한다. 다시 읽으면 그 사이트의 총평이 새것으로 바뀐다(지난 읽기의 총평을 현재로 보이게
+       * 두지 않는다).
+       */
+      const assessments: Record<string, unknown> = {}
+
+      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: ReferenceProgress['step'] = (adapter.masterSteps?.[0] ?? 'provision') as ReferenceProgress['step']
+        const track = (p: Omit<ReferenceProgress, 'siteCount'>) => {
+          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` 는 참조 이름이라 사이트 전부에 같다). */
+          /*
+           * 정책은 **선언이거나 의도에서 곧바로 따라오는 것**이다: `live=true` 는 미러를 띄우겠다는 뜻이고
+           * 미러는 정의상 `resync` 다(외부가 진실이므로 우리 과거를 이어 붙이지 않는다). 시뮬로 띄우려면
+           * 스스로 선언해야 한다 — 그 자리에서 우리가 고르면 재기동마다 이력을 지우는 트윈이 조용히 생긴다.
+           */
+          assessments[site.siteId] = assessMaster(master, site.siteId)
+          const policy = readRestartPolicy(restartPolicy ?? (live ? 'resync' : undefined), `importTwinReference("${source}")`)
+          track({ siteId: site.siteId, siteIndex, step: 'provision', done: declared ?? 0, total: stepTotal })
           const res = await 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 startReferenceLiveFeed(domainId, ref.adapterType, cfg, site, res.instanceId) : false
+            /* 읽기 커서를 저장할 자리를 함께 넘긴다 — 레퍼런스의 이름은 호스트가 붙이는 것이고
+               커넥터는 그것을 알 수 없다(§`startReferenceLiveFeed`). */
+            const wentLive = live
+              ? await startReferenceLiveFeed(domainId, ref.adapterType, cfg, site, res.instanceId, ref.source)
+              : false
             if (!wentLive) await TwinEngine.startFromRegistry(domainId, res.instanceId)
             instances.push({ siteId: site.siteId, instanceId: res.instanceId, spaceId: res.spaceId, mode: wentLive ? 'live' : 'sim', warnings: res.warnings })
           } else {
             instances.push({ siteId: site.siteId, instanceId: res.instanceId, spaceId: res.spaceId, mode: 'provisioned', warnings: res.warnings })
           }
         } catch (e: any) {
+          /*
+           * **실패한 단계를 그대로 알린다.** 화면이 진행 표시를 지우지 않고 그 자리를 붉게 두어야
+           * 사람이 「어디까지 갔는지」를 안다. 막힌 자리는 「끝낸 수」의 다음 단계다(위 주석).
+           */
+          const at = (adapter.masterSteps?.[lastDone] ?? lastStep) as ReferenceProgress['step']
+          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' })
         }
       }
@@ -600,6 +806,10 @@ export class TwinReferenceResolver {
         {
           status: 'connected',
           lastSyncedAt: new Date().toISOString(),
+          /* 못 옮긴 값을 **세어 남긴다**. 아무 인스턴스도 보고하지 않았으면 `null` — 「없었다」로 위장하지 않는다. */
+          lastWarningCount: instances.some((i: any) => Array.isArray(i.warnings))
+            ? instances.reduce((n: number, i: any) => n + (Array.isArray(i.warnings) ? i.warnings.length : 0), 0)
+            : null,
           /*
            * **영어 canonical 로 남긴다.** 이 값은 DB 에 저장되고 연결 화면이 그대로 뿌린다 — 예전에는
            * 한글 산문(`N개 사이트 실패`)이라 다섯 언어 화면에 한글이 새어 나갔다. 어댑터가 주는 사유도
@@ -607,7 +817,24 @@ export class TwinReferenceResolver {
            * 어느 사이트가 왜 실패했는지는 `failed[]` 가 답한다 — 화면이 그것을 보여 준다.
            */
           lastError: failed.length ? `${failed.length} of ${sites.length} site(s) failed: ${failed.map((f: any) => f.siteId).join(', ')}` : null,
-          scopeSpec: { ...((ref.scopeSpec as any) ?? {}), produced: [...prev, ...producedNew] }
+          /*
+           * ── 실패 사유를 **남긴다** (2026-08-21) ────────────────────────────────
+           *
+           * 사유는 대화상자에만 있었다. 닫으면 사라지고, 다시 보려면 같은 실패를 다시 만들어야 했다 —
+           * 실제로 「승화푸드」 연결이 그 상태였다(요약 한 줄만 남고 원인은 어디에도 없었다).
+           *
+           * `scopeSpec` 은 이미 이 레퍼런스의 부속 사실을 담는 자리이므로(`produced`) 스키마를 늘리지 않고
+           * 여기 적는다. 성공한 회차에는 **비운다** — 지나간 실패를 현재 상태처럼 보이게 두지 않는다.
+           */
+          scopeSpec: {
+            ...((ref.scopeSpec as any) ?? {}),
+            produced: [...prev, ...producedNew],
+            /* 이번에 읽은 사이트의 총평만 갈아 끼운다 — 읽지 않은 사이트의 것은 그대로 둔다. */
+            assessments: { ...(((ref.scopeSpec as any) ?? {}).assessments ?? {}), ...assessments },
+            ...(failed.length
+              ? { lastFailures: failed.map((f: any) => ({ siteId: f.siteId, error: f.error, at: new Date().toISOString() })) }
+              : { lastFailures: [] })
+          }
         } as any
       )
       return { ok: instances.length > 0, instances, failed }

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

@@ -1,5 +1,5 @@
 import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm'
-import { ObjectType, Field, ID } from 'type-graphql'
+import { ObjectType, Field, ID, Int } from 'type-graphql'
 
 import { Domain, ScalarObject } from '@things-factory/shell'
 
@@ -70,6 +70,44 @@ export class TwinReference {
   @Field({ nullable: true, description: 'Last connection/sync error message, if any.' })
   lastError?: string
 
+  /**
+   * 마지막 동기에서 **못 옮긴 값의 수**. `null` = 세지 않았다(0 과 다르다).
+   *
+   * 세지 않은 구조 인제스트는 도크를 랙으로 바꿔 놓고도 조용히 성공한다. 그 사실을 사후에 물을 수
+   * 있어야 단계 판정이 「구조는 됐다」를 말할 수 있다 — 없는 동안 판정은 늘 `unmeasured` 였다.
+   * 기본값을 두지 않는다: 0 을 기본으로 깔면 「경고 없었다」와 「세지 않았다」가 같아진다.
+   */
+  @Column({ type: 'int', nullable: true })
+  @Field(type => Int, { nullable: true, description: 'Number of values the last sync could not carry over (mapping fallbacks). Null means they were not counted at all, which is different from zero.' })
+  lastWarningCount?: number
+
+  /**
+   * **어디까지 읽었나** — 라이브 피드의 읽기 커서(§`LiveFeedContinuity`).
+   *
+   * ── 왜 저장하나 (2026-08-23 실측) ──────────────────────────────────────────
+   * 어댑터가 붙을 때마다 `Date.now() − 되돌아볼 날수` 로 창을 새로 만들고 있었다. 그래서 **재기동마다
+   * 미러의 과거가 잘렸다** — 작업 2,855 → 2,820(8시간 흐른 만큼). 미러가 아는 것이 「원본의 사실」이
+   * 아니라 「창의 함수」였고, 그 사실을 아무도 말하지 않았다.
+   *
+   * 커널이 그 갈림을 이미 적어 두었다(§`hydrateContinuity`): 「원천이 애초에 다시 말해 주지 않는 축」은
+   * 재기동 연속성으로 이어받는다. 「우리가 어디까지 읽었나」가 정확히 그 성질이므로 **어댑터의 사물함이
+   * 아니라 이 층**에 있다 — 원본이 늘 때마다 저장 기제가 늘고 그중 하나가 조용히 다르게 동작하지 않게.
+   *
+   * ── 왜 캐시가 아니라 표인가 ────────────────────────────────────────────────
+   * 만료되면 창이 다시 미끄러지고, 그 손실은 오류 없이 조용하다. 스냅샷 체크포인트와 성질이 다르다
+   * (그쪽은 잃어도 원천이 정정해 준다 — 이 값은 **잃으면 원천에 묻지 않게 된다**).
+   *
+   * 모양은 `{ streams: { [흐름]: { since?, seen[] } }, firstAttachedAt? }` 다. **흐름 이름은 어댑터가
+   * 정한다** — 원본마다 흐름 수와 뜻이 다르므로 이 층은 열쇠로만 다룬다. `simple-json` 이라 드라이버
+   * 다섯을 그대로 지난다.
+   *
+   * `firstAttachedAt` 은 「언제부터 아는가」다. 커널은 상한만 안다(`nowTime` = 마지막으로 들은 시각).
+   * 둘이 함께 「이 트윈이 아는 구간」이고, 화면이 수를 보일 때 그 구간을 말해야 한다.
+   */
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, { nullable: true, description: 'Live feed read cursor carried across restarts, keyed by adapter-defined stream. Null means the feed has never attached, and the next attach decides its first window.' })
+  liveCursor?: any
+
   @CreateDateColumn()
   @Field({ nullable: true, description: 'Timestamp when the reference was first created.' })
   createdAt?: Date

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

@@ -17,6 +17,19 @@ export type CommandAuditInput = {
   command: any
   /** 커널 판정. */
   ack: { accepted?: boolean; errorCode?: string; error?: string }
+  /**
+   * **원본(어댑터)이 준 답** — 허락과 일어남 사이에 끼어 있는 것을 같은 기록에 닫는다 (ADR-0029 §1 결정 C).
+   *
+   * ── 왜 이 칸이 필요한가 ──────────────────────────────────────────────────
+   * 명령이 원본으로 가면 감사는 「허락했다」까지만 증명한다 — 어댑터가 조용히 실패하면 원장에는 승인만
+   * 남는다. 그래서 어댑터의 답을 **같은 행**에 되적는다.
+   *
+   * 셋을 구별한다:
+   *  · 없음(`undefined`) — **원본에 묻지 않았다**(커널이 받은 명령이다). 「모른다」와 다르다.
+   *  · `{ answered: false }` — 물었는데 **답을 못 받았다** → `unknown` 으로 남긴다. 성공으로 적지 않는다.
+   *  · `{ answered: true, ok, code? }` — 원본이 답했다(적용·거절 모두 사실이다).
+   */
+  source?: { answered: boolean; ok?: boolean; code?: string }
   /** 세션이 아는 사용자 — **서버만 채운다.** */
   actor?: { id?: string; email?: string; name?: string }
   /** 서버 시각. 호출부가 주입해 테스트가 시간을 고정할 수 있게 한다. */
@@ -35,6 +48,13 @@ export type CommandAuditRow = {
   actorName?: string
   accepted: boolean
   errorCode?: string
+  /**
+   * 원본이 그래서 어떻게 했나 — `applied` · `refused` · `unknown`(물었지만 답이 없다).
+   * **없으면 묻지 않은 것이다**(커널이 받은 명령). 0 이나 성공으로 채우지 않는다.
+   */
+  sourceOutcome?: 'applied' | 'refused' | 'unknown'
+  /** 원본이 준 사유 코드 — 있으면 그대로. 우리가 지어내지 않는다. */
+  sourceCode?: string
   args?: any
   argsTruncated: boolean
 }
@@ -48,7 +68,7 @@ export function normalizeOrigin(v: unknown): CommandOrigin {
 const ARGS_MAX = 4000
 
 export function buildCommandAudit(input: CommandAuditInput): CommandAuditRow {
-  const { command, ack, actor, at } = input
+  const { command, ack, actor, at, source } = input
   const argsText = safeJson(command?.args)
   const truncated = argsText !== null && argsText.length > ARGS_MAX
   return {
@@ -57,6 +77,8 @@ export function buildCommandAudit(input: CommandAuditInput): CommandAuditRow {
     commandType: str(command?.type),
     origin: normalizeOrigin(command?.origin),
     reason: str(command?.reason),
+    /* 원본의 답 — 묻지 않았으면 칸을 만들지 않는다(모름과 구별한다). */
+    ...(source ? { sourceOutcome: sourceOutcomeOf(source), ...(source.code ? { sourceCode: source.code } : {}) } : {}),
     /* 신원 — 세션 값만. 커맨드에 실려 온 신원 주장은 쳐다보지 않는다. */
     actorId: str(actor?.id),
     actorEmail: str(actor?.email),
@@ -79,3 +101,14 @@ function safeJson(v: unknown): string | null {
     return null /* 순환 참조 등 — 못 재면 자르지 않는다(원본을 그대로 둔다) */
   }
 }
+
+/**
+ * 원본의 답을 세 값으로 — **답이 없으면 `unknown`**(성공으로 적지 않는다).
+ *
+ * 이 함수가 있는 이유: 「물었지만 답이 없다」를 실패로도 성공으로도 적을 수 없다. 실패로 적으면 일어난 일을
+ * 없던 일로 만들고, 성공으로 적으면 없던 일을 일어난 일로 만든다. 셋째 값이 사실이다.
+ */
+export function sourceOutcomeOf(source: { answered: boolean; ok?: boolean }): 'applied' | 'refused' | 'unknown' {
+  if (!source.answered || typeof source.ok !== 'boolean') return 'unknown'
+  return source.ok ? 'applied' : 'refused'
+}

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

@@ -99,6 +99,26 @@ export class TwinAuditEvent {
   reason?: string
 
   /* ── 신원: 세션에서만 온다 ── */
+  /*
+   * **원본이 그래서 어떻게 했나** — 허락과 일어남 사이에 끼어 있는 것을 같은 행에 닫는다
+   * (ADR-0029 §1 결정 C, 2026-08-19).
+   *
+   * 명령이 원본으로 가면 감사는 「허락했다」까지만 증명한다 — 어댑터가 조용히 실패하면 원장에는 승인만
+   * 남는다. 그래서 어댑터의 답을 되적는다.
+   *
+   *  · 비어 있음 — **원본에 묻지 않았다**(커널이 받은 명령이다). 「모른다」와 다르다.
+   *  · `unknown` — 물었는데 **답을 못 받았다**. 성공으로 적지 않는다.
+   *  · `applied` · `refused` — 원본이 답했다(둘 다 사실이다).
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: "What the source did with it: 'applied' | 'refused' | 'unknown' (asked but no answer). Empty means the source was not asked — the kernel took the command." })
+  sourceOutcome?: string
+
+  /** 원본이 준 사유 코드 — 있으면 그대로 적는다(우리가 지어내지 않는다). */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Reason code the source returned, as it gave it.' })
+  sourceCode?: string
+
   @Column({ nullable: true })
   @Field({ nullable: true, description: 'Approving user id, stamped by the server from the session.' })
   actorId?: string