@things-factory/headless-twin 10.0.12 → 10.0.13

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

@@ -1,3 +1,6 @@
+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'
@@ -207,8 +210,37 @@ 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 })
       /*
        * **어느 현장의 트윈이었나를 지킨다** — 다시 읽기는 구조만 새로 그리는 일이고, 현장 소속은 그때
        * 사람이 고른 것이다. 기억이 없는 옛 트윈은 **지금 있는 현장**을 그대로 쓴다(빈손으로 두면 템플릿
@@ -223,14 +255,51 @@ export class TwinReferenceResolver {
         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`)
@@ -267,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`
@@ -368,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 {
@@ -445,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)')
@@ -601,9 +703,60 @@ 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` 는 참조 이름이라 사이트 전부에 같다). */
           /*
@@ -611,7 +764,9 @@ export class TwinReferenceResolver {
            * 미러는 정의상 `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 } : {}) } },
@@ -619,15 +774,27 @@ export class TwinReferenceResolver {
             { 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' })
         }
       }
@@ -639,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개 사이트 실패`)이라 다섯 언어 화면에 한글이 새어 나갔다. 어댑터가 주는 사유도
@@ -646,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-control/twin-control-mutation.ts

@@ -1,3 +1,4 @@
+import { twinError } from '../../engine/log.js'
 import { Arg, Ctx, Mutation, Query, Resolver, Directive } from 'type-graphql'
 
 import { validateScenario } from '@operato/twin-kernel'
@@ -42,7 +43,7 @@ export class TwinControlMutation {
     const ack = await TwinEngine.dispatchCommand(domainId, instanceId, command)
     /* 라이브 구조 변이(resource.add)는 저장 model 에도 반영 — 프로비저닝 편집기·재기동이 추가분을 잃지 않게. */
     if (ack?.accepted && command?.type === 'resource.add') {
-      await TwinEngine.syncBoardEquipment(domainId, instanceId).catch(err => console.error('twin syncBoardEquipment fail', err))
+      await TwinEngine.syncBoardEquipment(domainId, instanceId).catch(err => twinError('twin syncBoardEquipment fail', err))
     }
     /*
      * 감사 기록 — 승인 게이트가 앞을 막고, 이 줄이 뒤를 설명한다. 둘 다 있어야 "사람 손을 거쳤다" 를
@@ -56,7 +57,7 @@ export class TwinControlMutation {
       const repo = getRepository(TwinAuditEvent)
       await repo.save(repo.create({ domain: context.state.domain, instanceId, ...audit }))
     } catch (err) {
-      console.error(`[twin-control] command audit not recorded for "${instanceId}"`, err)
+      twinError(`[twin-control] command audit not recorded for "${instanceId}"`, err)
     }
 
     /* 거절 사유는 **언어 중립 코드**로 함께 돌려준다 — 화면이 `twin.cmderr.<code>` 로 사람 말을 만든다. */
@@ -132,7 +133,7 @@ export class TwinControlMutation {
       await repo.save(repo.create({ domain: context.state.domain, instanceId, ...audit }))
     } catch (err) {
       /* 기록이 실패해도 결과는 돌려준다 — 다만 삼키지 않는다(「기록 없음」과 「일 없음」을 구별해야 한다). */
-      console.error(`[twin-control] source control audit not recorded for "${instanceId}"`, err)
+      twinError(`[twin-control] source control audit not recorded for "${instanceId}"`, err)
     }
     return result
   }

package/server/service/twin-event/journal-count.ts

@@ -0,0 +1,53 @@
+/*
+ * 저널을 **상한까지만 센다** — 세는 것도 읽는 것이다 (2026-08-22).
+ *
+ * ── 왜 (실측) ───────────────────────────────────────────────────────────────
+ * 조건에 맞는 행을 전부 세는 질의는 행을 실어 오지 않아도 비싸다. 개발 저널에서 트윈 하나가 358만
+ * 행이었고 그 한 번이 **5.32초**였다. 색인만 상한까지 읽으면 같은 조건에서 **0.04초**다(130배).
+ *
+ * 그 5초 동안 이벤트 루프는 다른 요청을 처리하지 못한다 — 이력 화면 한 번, 준비도 화면 한 번이
+ * 사용자에게는 「눌렀는데 아무 반응이 없다」로 나타난다. 준비도 화면은 그런 세기를 **넷** 했다.
+ *
+ * ── 규율 ────────────────────────────────────────────────────────────────────
+ * 세는 목적이 둘 중 하나다.
+ *  ① **판정** — 「한 건이라도 있나」. 그때는 하나만 찾으면 끝이다(`anyJournalRow`).
+ *  ② **표시** — 사람에게 수를 보인다. 그때는 상한까지 세고, 넘으면 **모른다고 말한다**(`countUpTo`).
+ *
+ * 상한을 넘었을 때 상한값을 전체로 적으면 화면이 거짓을 말한다. 그래서 `capped` 를 함께 낸다 —
+ * 없는 것과 모르는 것을 가르는 이 프로젝트의 규율이 세기에도 같이 적용된다.
+ */
+import type { ObjectLiteral, Repository } from 'typeorm'
+
+/** 표시용 세기의 기본 상한 — 화면이 한 번에 보여 줄 범위를 훨씬 넘는 값. */
+export const JOURNAL_COUNT_CAP = 10_000
+
+export interface CappedCount {
+  /** 센 수. `capped` 면 상한까지만 센 값이므로 **전체가 아니다**. */
+  count: number
+  /** 상한을 넘었나 — 그때 전체 수는 모르는 것이 사실이다. */
+  capped: boolean
+}
+
+/**
+ * 상한까지만 세기 — 키 컬럼만 읽으므로 행 본문을 만들지 않는다.
+ *
+ * `count()` 를 쓰지 않는 이유: 그것은 상한을 받지 않는다(조건에 맞는 전부를 센다).
+ */
+export async function countUpTo<T extends ObjectLiteral>(
+  repo: Repository<T>,
+  where: any,
+  cap = JOURNAL_COUNT_CAP
+): Promise<CappedCount> {
+  const rows = await repo.find({ where, select: ['id'] as any, take: cap + 1 })
+  return rows.length > cap ? { count: cap, capped: true } : { count: rows.length, capped: false }
+}
+
+/**
+ * 한 건이라도 있나 — **판정에는 수가 필요 없다.**
+ *
+ * 예전에는 전부 센 뒤 `> 0` 을 봤다. 그 답을 얻는 데 358만 행을 세고 있었다.
+ */
+export async function anyJournalRow<T extends ObjectLiteral>(repo: Repository<T>, where: any): Promise<boolean> {
+  const rows = await repo.find({ where, select: ['id'] as any, take: 1 })
+  return rows.length > 0
+}

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

@@ -1,3 +1,4 @@
+import { twinWarn } from '../../engine/log.js'
 /*
  * 저널 검색 키 추출 — **순수**. 인제스트가 기록할 때 한 번 뽑아 인덱스 가능한 실컬럼으로 승격한다.
  *
@@ -18,6 +19,7 @@
 
 /** 승격된 검색 키 — 전부 선택적. 뽑히지 않으면 **빈 문자열이 아니라 undefined**(결측≠빈값). */
 export interface TwinEventKeys {
+  action?: string
   bizStep?: string
   epc?: string
   orderId?: string
@@ -37,7 +39,7 @@ function clip(v: unknown, field: string): string | undefined {
   const s = String(v)
   if (!s) return undefined
   if (s.length <= MAX_KEY) return s
-  console.warn(
+  twinWarn(
     `[twin-event-keys] ${field} exceeds ${MAX_KEY} chars and was clipped for indexing — ` +
       `search on this value may be incomplete. payload keeps the full value. (${s.slice(0, 60)}…)`
   )
@@ -90,9 +92,22 @@ export function equipmentIdOf(envelope: any): string | undefined {
   return d.moverId ?? undefined
 }
 
+/**
+ * EPCIS 행위 — `ADD`·`OBSERVE`·`DELETE`. 세 값이 아니면 `undefined`(원천의 잡값을 색인에 넣지 않는다).
+ *
+ * 이 키는 검색 축이 아니라 **판별식**이다: 되풀어 읽는 스냅샷은 원리적으로 `DELETE` 를 못 낸다.
+ * 그래서 「이 트윈이 반출을 한 번이라도 접었는가」가 진짜 delta 피드의 증거인데, payload 안에 있는
+ * 동안에는 5개 드라이버 어디에서도 그 질문을 할 수 없었다. 운영 델타에는 행위가 없다 — 비운다.
+ */
+export function actionOf(envelope: any): string | undefined {
+  const a = (envelope?.data ?? envelope ?? {}).action
+  return a === 'ADD' || a === 'OBSERVE' || a === 'DELETE' ? a : undefined
+}
+
 /** 한 이벤트에서 승격 키 전부 — 기록 경로가 이 함수 하나만 부른다. */
 export function twinEventKeys(envelope: any): TwinEventKeys {
   return {
+    action: actionOf(envelope),
     bizStep: clip(bizStepOf(envelope), 'bizStep'),
     epc: clip(epcOf(envelope), 'epc'),
     orderId: clip(orderOf(envelope), 'orderId'),

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

@@ -14,8 +14,32 @@ export class TwinEventList {
   @Field(type => [TwinEvent], { description: 'The events on this page, ordered by the requested sorting (revision descending by default).' })
   items: TwinEvent[]
 
-  @Field(type => Int, { description: 'Total number of events matching the filters, ignoring pagination. Lets the caller show an honest "shown of total" count instead of silently truncating.' })
-  total: number
+  /*
+   * 전체 수 — **상한을 넘으면 비운다.**
+   *
+   * 세는 데도 값이 든다(2026-08-22 실측: 저널 358만 행인 트윈에서 전량 세기 5.32초 · 상한 1만까지
+   * 0.04초). 그래서 상한까지만 세고, 넘으면 「모른다」로 둔다. 그때 상한값을 전체로 적으면 화면이
+   * 거짓을 말한다 — 없는 것과 모르는 것을 가르는 것이 이 필드의 규율이다.
+   */
+  @Field(type => Int, {
+    nullable: true,
+    description:
+      'Total number of events matching the filters, ignoring pagination. Lets the caller show an honest "shown of total" count instead of silently truncating. NULL when the server stopped counting at countCap: the exact total is then unknown, and capped says so — do not render the cap as if it were the total.'
+  })
+  total?: number
+
+  @Field({
+    nullable: true,
+    description:
+      'True when there are more matching events than countCap, so total could not be established. The caller should say "first N shown" and offer narrowing rather than implying it received everything.'
+  })
+  capped?: boolean
+
+  @Field(type => Int, {
+    nullable: true,
+    description: 'The counting limit the server applied. Reported so the screen can say how far the count is trustworthy instead of guessing.'
+  })
+  countCap?: number
 
   /*
    * 다음 페이지 커서. 저널은 **머리에 계속 쌓이는 목록**이라 offset 으로 뒤를 읽으면

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

@@ -34,6 +34,8 @@ import { Domain, ScalarObject } from '@things-factory/shell'
 @Index('ix_twin_event_4', (e: TwinEvent) => [e.domain, e.instanceId, e.orderId], { unique: false })
 /* ix_5 — "이 지시가 무엇을 일으켰나". 감사 기록의 commandId 로 저널을 다시 계산하는 축. */
 @Index('ix_twin_event_5', (e: TwinEvent) => [e.domain, e.correlationId], { unique: false })
+/* ix_6 — "반출을 한 번이라도 접었나". 없으면 그 질문이 인스턴스 저널 전량 주사가 된다. */
+@Index('ix_twin_event_6', (e: TwinEvent) => [e.domain, e.instanceId, e.action], { unique: false })
 @ObjectType({ description: 'Append-only twin event journal record (EPCIS event or operational delta).' })
 export class TwinEvent {
   @PrimaryGeneratedColumn('uuid')
@@ -132,6 +134,11 @@ export class TwinEvent {
   @Field({ nullable: true, description: 'Id of the command that caused this fact (kernel correlation id; defaults to the commandId). Empty for facts that simulation time produced rather than a command.' })
   correlationId?: string
 
+  /* 옛 행은 비어 있다 — 승격 전에 기록된 것이라 **모른다**(0 이나 OBSERVE 로 위장하지 않는다). */
+  @Column({ length: 16, nullable: true })
+  @Field({ nullable: true, description: 'EPCIS action (ADD / OBSERVE / DELETE), promoted from the payload. Empty for operational deltas, and for rows journaled before this column existed.' })
+  action?: string
+
   @Column({ length: 255, nullable: true })
   @Field({ nullable: true, description: 'Business step (CBV bizStep tail), promoted from the payload for indexed filtering.' })
   bizStep?: string

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

@@ -1,3 +1,4 @@
+import { twinLog } from '../../engine/log.js'
 import { Arg, Ctx, Int, Mutation, Query, Resolver, Directive} from 'type-graphql'
 
 import { getRepository, ScalarObject } from '@things-factory/shell'
@@ -193,7 +194,7 @@ export class TwinForecastQuery {
     const basis = await TwinEngine.modelBasis(domainId, instanceId)
     const stale = !!stored && modelBasisChanged(stored.basis, basis)
     if (stale) {
-      console.log(
+      twinLog(
         `[twin-forecast] "${instanceId}": calibration not applied — model changed since it was learned.` +
           ` learned on: ${describeModelBasis(stored!.basis)} / now: ${describeModelBasis(basis)}`
       )

package/server/service/twin-ingest-window/index.ts

@@ -0,0 +1,7 @@
+import { TwinIngestWindow } from './twin-ingest-window.js'
+import { TwinIngestWindowQuery } from './twin-ingest-window-query.js'
+
+export const entities = [TwinIngestWindow]
+export const resolvers = [TwinIngestWindowQuery]
+
+export { installIngestWindowWriter } from './twin-ingest-window-writer.js'