@things-factory/headless-twin 10.0.12 → 10.0.13

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

@@ -1,8 +1,12 @@
+import { axisSeenInJournal } from './axis-journal-evidence.js'
+import { statusTally } from './status-tally.js'
+import { TwinEvent } from '../twin-event/twin-event.js'
 import { Arg, Ctx, Query, Resolver } from 'type-graphql'
 
 import { ScalarObject, getRepository } from '@things-factory/shell'
 
 import { TwinEngine } from '../../engine/index.js'
+import { modelGapOf } from '../../engine/model-gap.js'
 import { readBoardEquipment } from '@operato/twin-kernel'
 import { TwinInstance } from '../twin-instance/twin-instance.js'
 import { TwinSpace } from '../twin-space/twin-space.js'
@@ -98,6 +102,27 @@ function valuesAt(obj: any, field: string): any[] {
 
 const idOf = (o: any): string | null => (typeof o === 'string' ? o : o?.id ?? o?.key ?? o?.gtin ?? null)
 
+/** 상태가 빈 축의 이유 — 저널에 그 사실이 있으면 그렇게 말한다. 판단할 수 없으면 예전 그대로. */
+async function emptyStateReason(domainId: string, instanceId: string, axis: string): Promise<string> {
+  try {
+    const seen = await axisSeenInJournal(getRepository(TwinEvent), { domain: { id: domainId }, instanceId }, axis)
+    /* 판단할 수 없는 축(`null`)은 예전 답을 그대로 쓴다 — 모르는 것을 새 사실로 만들지 않는다. */
+    return seen ? 'observed-not-in-state' : 'none-yet'
+  } catch {
+    /* 저널을 못 읽었다고 카드가 없는 말을 하지는 않는다. */
+    return 'none-yet'
+  }
+}
+
+/**
+ * 되세운 상태를 담아 둔다 — **열쇠에 저널 끝 리비전이 들어 있어** 새 사건이 오면 저절로 낡는다.
+ *
+ * 접기는 저널 전체를 훑는 일이라(리비전 12만에서 2~3초) 모델 화면을 열 때마다 그 값을 낼 수 없다.
+ * 프로세스 안에만 두고 몇 개만 남긴다 — 다시 뜨면 다시 접는다(정확함이 캐시보다 앞선다).
+ */
+const RECALL_CACHE = new Map<string, { snap: any; heardAt: string | null }>()
+const RECALL_CACHE_MAX = 8
+
 @Resolver()
 export class TwinModelQuery {
   /**
@@ -188,6 +213,60 @@ export class TwinModelQuery {
         }
         return { snap, folded, observing }
       })())
+
+    /*
+     * ── **라이브가 잊은 것을 저널이 안다** (2026-08-23) ─────────────────────────
+     *
+     * 미러의 관측은 메모리에만 산다. 재기동하면 빈 채로 시작하고, 원본이 다시 말해 줄 때 채워진다 —
+     * 그런데 읽기 커서가 정직해진 뒤로는 원본이 **지난 것을 다시 말하지 않는다.** 그래서 재고 741건이
+     * 저널에 있는데 화면은 「0」을 보였다. 사용자가 「재고현황이 없다」고 물은 자리가 이것이다.
+     *
+     * 그 0 은 사실이 아니라 **우리가 잊은 것**이다. 저널을 접으면 그대로 되살아난다(실측: 리비전
+     * 97,689 을 2.4초에 접어 물품 741 · 작업 9,145 · 지시 2,856).
+     *
+     * ── 그래서 접는다. 다만 **언제 들은 값인지 함께 낸다** ──────────────────────
+     * 저널을 접는 것은 **원천이 우리에게 말한 것을 다시 세우는 일**이지, 없는 값을 심는 일이 아니다.
+     * 그러나 물품·재고처럼 **절대값인 축**은 우리가 못 듣는 사이 떠났을 수 있다 — 그래서 값과 함께
+     * `heardAt`(그 접기의 시계)을 낸다. 사용자가 신선도를 스스로 판정할 수 있어야 하고, 화면은 그것을
+     * 값 옆에 적는다. 시각 없이 수만 내면 낡은 값을 지금으로 읽는다.
+     *
+     * 접는 조건을 좁게 둔다: **관측 축이 비어 있고, 저널에 그 축의 사실이 있을 때만**(그 판정은 색인
+     * 한 줄이다). 그리고 한 요청에 **한 번만** 접는다 — 위 `stateOnce` 와 같은 규율이다.
+     */
+    let journalPromise: Promise<{ snap: any; heardAt: string | null } | null> | null = null
+    const journalOnce = () =>
+      (journalPromise ??= (async () => {
+        try {
+          const tip = await getRepository(TwinEvent).findOne({
+            where: { domain: { id: domainId } as any, instanceId } as any,
+            order: { revision: 'DESC' } as any
+          })
+          if (!tip?.revision) return null
+          /*
+           * **한 번 접은 것을 다시 접지 않는다.** 접기는 저널 전체를 훑는 일이다(리비전 12만에서 2~3초).
+           * 이 화면은 사람이 여러 번 들어오는 자리이므로 그대로 두면 매번 그 값을 낸다 — 그리고 저널이
+           * 수백만 행이 되면 그 비용이 화면을 못 쓰게 만든다.
+           *
+           * 열쇠에 **저널 끝의 리비전**을 넣는다: 새 사건이 오면 열쇠가 달라지므로 캐시가 저절로 낡는다
+           * (캐시가 사실을 이기지 않는다). 프로세스 안에만 두고 몇 개만 남긴다.
+           */
+          const key = `${domainId}:${instanceId}:${tip.revision}`
+          const hit = RECALL_CACHE.get(key)
+          if (hit) return hit
+          const snap = unwrapState(await TwinEngine.recover(domainId, instanceId, tip.revision))
+          if (!snap) return null
+          /* 그 접기의 시계가 「언제 들은 값인가」다. 없으면 저널 끝의 사건 시각으로 답한다. */
+          const out = { snap, heardAt: (snap as any).nowTime ?? tip.eventTime ?? null }
+          RECALL_CACHE.set(key, out)
+          /* 오래된 열쇠부터 버린다 — 트윈 몇 개를 번갈아 봐도 메모리가 자라지 않게. */
+          while (RECALL_CACHE.size > RECALL_CACHE_MAX) RECALL_CACHE.delete(RECALL_CACHE.keys().next().value as string)
+          return out
+        } catch {
+          /* 접지 못했으면 아무 말도 만들지 않는다 — 라이브가 말한 것을 그대로 둔다. */
+          return null
+        }
+      })())
+
     const concepts = await Promise.all(
       TWIN_AXES.map(async (a: any) => {
         /*
@@ -210,6 +289,17 @@ export class TwinModelQuery {
             count: null,
             notApplicable: true,
             emptyBecause: 'not-applicable',
+            /*
+             * **그 개념의 성질** — 선언인가 관측인가 (2026-08-22).
+             *
+             * `basis` 와 다르다: `basis` 는 「이 값이 어디서 왔나」이고 트윈마다·시점마다 달라진다(같은
+             * 축이 한 트윈에서 `journal`, 다른 트윈에서 `state` 로 온다). 그것으로 묶으면 같은 축이 화면
+             * 마다 다른 묶음에 들어간다. `source` 는 트윈과 무관하게 고정이므로 묶는 축이 된다.
+             *
+             * 화면이 축 이름을 열거하지 않아도 되고, 축이 늘면 자동으로 맞는 묶음에 들어간다 —
+             * 카탈로그가 정본이다.
+             */
+            source: axisSource(a.axis),
             basis: 'declaration'
           }
         }
@@ -243,6 +333,15 @@ export class TwinModelQuery {
          * 0 으로 내면 "작업이 없는 공장" 으로 읽히고, 그건 거짓이다(관측이 없는 것과 0 건은 다르다).
          * 이 화면이 관측 열에서 내내 지켜 온 구분을 카드에서도 지킨다.
          */
+        /*
+         * **「아직 없다」와 「왔는데 상태에 없다」는 다른 사실이다** (2026-08-22).
+         *
+         * 화면이 「작업 — 아직 하나도 없습니다」라고 말했는데 저널에는 `task.status` 5,786건이 있었고
+         * 마지막 상태가 `in-progress` 였다(원인은 커널의 내보내기였고 그 레인에 넘겼다). 카드가 단정한
+         * 탓에 사용자가 그 차이를 직접 조사해야 했다 — 화면이 아는 것을 말하지 않은 자리다.
+         *
+         * 그래서 상태가 빈 축은 저널을 **한 건만** 물어본다(색인 한 줄, `journal-count` 의 문).
+         */
         if (axisSource(a.axis) === 'state') {
           /* 스냅샷은 `{revision, state}` 봉투다 — 벗기지 않으면 축이 한 겹 안에 있어 언제나 `null` 이
              된다(커널은 도는데 카드가 "모름" 으로 보였다). 벗기는 규칙의 집은 `warm-start` 하나다. */
@@ -255,7 +354,25 @@ export class TwinModelQuery {
           const { snap, folded, observing } = await stateOnce()
           /* 축이 사는 자리는 **커널 선언이 말한다**(`path`) — 축 이름으로만 읽으면 중첩된 축이
              언제나 「관측 없음」이 된다(에너지의 수요 구간이 그렇다). 규칙은 `axisValueOf` 한 곳. */
-          const bucket = snap ? axisValueOf(snap, a) ?? null : null
+          let bucket = snap ? axisValueOf(snap, a) ?? null : null
+          let heardAt: string | null = null
+          let fromJournal = false
+          /*
+           * 라이브가 잊은 축은 **저널에서 되세운다**(§`journalOnce`). 그 축의 사실이 저널에 있을 때만
+           * 접고, 값과 함께 「언제 들은 값인가」를 낸다 — 시각 없이 수만 내면 낡은 값을 지금으로 읽는다.
+           */
+          if (!folded && Array.isArray(bucket) && bucket.length === 0) {
+            const seen = await axisSeenInJournal(getRepository(TwinEvent), { domain: { id: domainId }, instanceId }, a.axis).catch(() => null)
+            if (seen) {
+              const j = await journalOnce()
+              const jb = j?.snap ? axisValueOf(j.snap, a) ?? null : null
+              if (Array.isArray(jb) && jb.length) {
+                bucket = jb
+                heardAt = j?.heardAt ?? null
+                fromJournal = true
+              }
+            }
+          }
           return {
             axis: a.axis,
             label: a.label,
@@ -264,13 +381,34 @@ export class TwinModelQuery {
             standardClass: a.standardClass,
             typeRole: a.typeRole ?? null,
             count: Array.isArray(bucket) ? bucket.length : null,
+            /*
+             * **수 하나가 뜻을 바꾸는 자리** (2026-08-23).
+             *
+             * 미러가 완료된 작업까지 상태에 들고 있게 되면서 「작업 2,820」이 되었다. 이 카드는 상태의
+             * 인구조사이므로 그 수가 맞다 — 그런데 사람은 그것을 「지금 할 일 2,820건」으로 읽는다.
+             * 수를 줄여 거짓으로 만드는 대신 **무엇으로 이루어진 수인지** 함께 낸다.
+             *
+             * 낱말은 커널의 것을 그대로 쓴다(`created`·`assigned`·`in-progress`·`completed`). 화면이
+             * 라벨을 입히고, 없으면 낱말이 그대로 보여 누락이 드러난다.
+             */
+            ...statusTally(bucket),
             /*
              * **비었으면 왜 비었는지 말한다.** 0 과 `null` 만 내면 화면은 "없다" 까지만 말하고, 사용자는
              * "안 적어 놨나 · 아직 안 일어났나 · 못 세었나" 를 구별할 수 없다. 이 화면이 관측 열에서
              * 내내 지켜 온 구분(§observedAbsence)을 카드에서도 지킨다.
              */
-            ...(Array.isArray(bucket) ? (bucket.length ? {} : { emptyBecause: 'none-yet' }) : { emptyBecause: 'not-observed' }),
-            basis: folded ? 'journal' : 'state',
+            ...(Array.isArray(bucket)
+              ? bucket.length
+                ? {}
+                : { emptyBecause: await emptyStateReason(domainId, instanceId, a.axis) }
+              : { emptyBecause: 'not-observed' }),
+            source: axisSource(a.axis),
+            basis: folded || fromJournal ? 'journal' : 'state',
+            /*
+             * **언제 들은 값인가** — 저널에서 되세운 축만 갖는다. 라이브가 답한 축은 지금이므로 없다.
+             * 이 값이 없으면 화면이 낡은 수를 지금으로 읽는다(그 구별이 이 카드의 전부다).
+             */
+            ...(fromJournal && heardAt ? { heardAt, recalled: true } : {}),
             observing,
             /* 선언이 아니라 관측인 축 — 화면이 "원본이 침묵했다" 로 읽지 않게 사실로 말한다. */
             observedOnly: true,
@@ -301,6 +439,7 @@ export class TwinModelQuery {
                   entity && inDocument > 0 ? 'not-projected' : raw == null ? 'not-declared' : 'declared-empty'
               }),
           /* 'rows' = DB 가 셌다(질의 가능) · 'document' = 문서를 세었다(아직 이주 전). */
+          source: axisSource(a.axis),
           basis: entity ? 'rows' : 'document',
           ...(entity ? { documentCount: inDocument, stale } : {}),
           /* 표준 투영이 없는 축은 **숨기지 않고** 그 사실을 낸다(ADR-0031). */
@@ -321,12 +460,24 @@ export class TwinModelQuery {
      * 트윈이 안 실행 중이면 비교할 상대가 없다 — 그때는 `null` 이다(0 이 아니다. 없는 것과
      * 세어 보지 못한 것은 다르다).
      */
+    /*
+     * 도출은 **한 벌**이다(`engine/model-gap.ts`). 예전에는 이 자리에 인라인으로 있었는데, 같은 사실을
+     * 「현장과 맞춰지고 있나」 화면도 물어야 해서 두 곳이 다른 수를 말할 위험이 생겼다.
+     *
+     * 이 화면은 **전체 목록**이 필요하다(인스펙션이니까). 그래서 상한 없는 원본을 여기서 만들고,
+     * 상한이 걸린 요약은 `modelGapOf` 가 답한다 — 같은 판정(`origin === 'observed'`)을 쓴다.
+     */
     const snap = TwinEngine.snapshot(domainId, instanceId)
+    const gap = modelGapOf(snap)
     const observedOnly = snap
       ? {
           equipment: (snap.equipment ?? []).filter((e: any) => e?.origin === 'observed').map((e: any) => e.id),
           locations: (snap.locations ?? []).filter((l: any) => l?.origin === 'observed').map((l: any) => l.id),
-          persons: (snap.persons ?? []).filter((p: any) => p?.origin === 'observed').map((p: any) => p.id)
+          persons: (snap.persons ?? []).filter((p: any) => p?.origin === 'observed').map((p: any) => p.id),
+          /* 커널이 담을 줄 몰라 세어 둔 사건·모르는 설비 보고 — 인스펙션이 이미 물을 자리다. */
+          unhandled: gap?.unhandled ?? [],
+          unknownEquipmentReports: gap?.unknownEquipmentReports ?? null,
+          notCovered: gap?.notCovered ?? []
         }
       : null
 

package/server/service/twin-model/twin-model-tree-query.ts

@@ -1,3 +1,4 @@
+import { nameIndex, namesFor } from './name-index.js'
 import { Arg, Ctx, Int, Query, Resolver } from 'type-graphql'
 
 import { ScalarObject, getRepository } from '@things-factory/shell'
@@ -171,6 +172,12 @@ export class TwinModelTreeQuery {
       items,
       edges,
       /* 수량을 하나라도 모르면 아래 합계가 성립하지 않는다는 사실을 그대로 낸다. */
+      /*
+       * **이름을 함께 낸다** (2026-08-22). 나무의 줄이 id 만 보이면 사용자는 그 노드가 무엇인지 알 수
+       * 없다 — 사용자의 말: 「각 노드의 식별자가 반복되어서 이해가 어렵다. 식별자와 이름이 보이면.」
+       * 목록·항목 화면이 쓰는 것과 **같은 표**를 쓴다(`name-index`) — 두 벌이면 한쪽만 고쳐진다.
+       */
+      names: namesFor(items, nameIndex(inst.model ?? {})),
       qtyIncomplete: edges.some(e => e.step == null),
       cycles: [...new Set(cycles)],
       truncated: { depth: depthTruncated, items: itemTruncated, depthCap, itemCap },

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

@@ -0,0 +1,3 @@
+import { TwinReadinessQuery } from './twin-readiness-query.js'
+
+export const resolvers = [TwinReadinessQuery]

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

@@ -0,0 +1,96 @@
+import { Arg, Ctx, Query, Resolver } from 'type-graphql'
+
+import { getRepository, ScalarObject } from '@things-factory/shell'
+
+import { TwinEngine } from '../../engine/index.js'
+import { assessSuite, SUITE_SPEC, type SuiteFacts } from '../../engine/integration-runner.js'
+import { readSpecCoverage } from '../../engine/spec-coverage.js'
+import { capabilitiesOf, getAdapter } from '../reference/reference-adapter.js'
+import { TwinEvent } from '../twin-event/twin-event.js'
+import { anyJournalRow, countUpTo } from '../twin-event/journal-count.js'
+import { TwinInstance } from '../twin-instance/twin-instance.js'
+import { TwinReference } from '../reference/twin-reference.js'
+
+/*
+ * 도입 단계 — **「이 트윈은 어디까지 증명됐나」.**
+ *
+ * `twinIngestHealth` 와 묻는 것이 다르다: 그쪽은 「지금 현장과 맞춰지고 있나」(피드의 건강)이고,
+ * 여기는 「구조·라이브·예측·폐루프 중 어디까지 **증거로** 섰나」다. 체크리스트가 아니라 판정이므로
+ * 사람이 체크해서 초록으로 만들 수 없다.
+ *
+ * **접속 프로브는 여기서 돌리지 않는다.** 조회마다 고객 시스템을 두드리면 화면을 열 때마다 남의
+ * 운영계에 부하가 간다. 그래서 `connectOk` 는 `null`(안 돌렸다)이고, 계획의 첫 칸이 접속 확인이 된다.
+ */
+@Resolver()
+export class TwinReadinessQuery {
+  @Query(returns => ScalarObject, {
+    nullable: true,
+    description:
+      'Which adoption stage this twin has actually reached, judged from evidence rather than a checklist: structure, live, forecast, closed-loop. Each stage reports what blocks it and which signals could not be measured at all — an unmeasured signal never counts as achieved, so a half-run suite cannot claim green. Probes that do not apply to this twin (live probes on a simulation, mapping-warning probes on a template-built twin) come back as notApplicable with a reason, which is neither a pass nor a gap. `forbiddenClaims` lists the claims that must not be made yet (realtime, prediction, automatic control). The connection probe is not run here because a read query should not hit the source system on every page load, so it appears in `planned` as the next step to take. Null if the instance is not in the current domain.'
+  })
+  async twinAdoptionPath(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<any> {
+    const domainId = context.state.domain.id
+    if (!TwinEngine.owns(domainId, instanceId) && !(await TwinEngine.ownsRegistered(domainId, instanceId))) return null
+
+    const inst = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })
+    if (!inst) return null
+    const ref = await getRepository(TwinReference)
+      .findOne({ where: { domain: { id: domainId }, source: instanceId } })
+      .catch(() => null)
+
+    const mode = TwinEngine.modeOf(domainId, instanceId)
+    const snapshot = TwinEngine.owns(domainId, instanceId) ? TwinEngine.snapshot(domainId, instanceId) : undefined
+    const events = getRepository(TwinEvent)
+
+    /*
+     * 저널에서 센다 — **재시작에도 남는 자리**다. 인메모리 계기로 세면 재기동마다 0 이 되고, 그 0 이
+     * 「세었는데 반출이 없었다」로 읽혀 라이브 단계를 거짓으로 막는다.
+     *
+     * `action` 승격 전에 기록된 행은 세어지지 않는다. 그래서 반출이 **한 건도 없고** 승격 이후 유입도
+     * 없으면 `null`(모른다)로 낸다 — 옛 저널을 「반출 0건」으로 단정하지 않는다.
+     */
+    /*
+     * **상한까지만 센다** (2026-08-22 실측). 예전에는 넷을 전부 세었고, 저널 358만 행인 트윈에서 한 번이
+     * 5.32초라 이 화면 하나가 20초를 썼다. 판정에 쓰이는 것은 문턱(≥1)이므로 상한까지의 수로 충분하고,
+     * 승격 여부는 **한 건만 찾으면** 답이 난다(수가 필요 없다).
+     */
+    const scope = { domain: { id: domainId }, instanceId }
+    const journal = await countUpTo(events, scope)
+    const removalCount = await countUpTo(events, { ...scope, action: 'DELETE' })
+    const journalTotal = journal.count
+    const removals = removalCount.count
+    const anyPromoted =
+      removals > 0 ||
+      (await anyJournalRow(events, { ...scope, action: 'OBSERVE' })) ||
+      (await anyJournalRow(events, { ...scope, action: 'ADD' }))
+
+    const modelLocations = Array.isArray((inst.model as any)?.locations) ? (inst.model as any).locations.length : null
+
+    const facts: SuiteFacts = {
+      subject: mode === 'live' ? 'live' : mode === 'sim' ? 'sim' : 'unknown',
+      fromReference: !!ref,
+      adapterCapabilities: ref?.adapterType ? capabilitiesOf(getAdapter(ref.adapterType)) : [],
+      connectOk: null, // 조회에서 남의 운영계를 두드리지 않는다
+      /* 이 레퍼런스가 트윈을 세운 사이트 수 — 발견의 결과다(발견 자체를 다시 돌리지 않는다). */
+      siteCount: ref ? ((ref.scopeSpec as any)?.produced?.length ?? null) : null,
+      locationCount: snapshot?.locations?.length ?? modelLocations,
+      itemCount: snapshot?.items?.length ?? null,
+      lastWarningCount: ref?.lastWarningCount ?? null,
+      journalTotal,
+      /* 승격 이후 유입이 하나도 없으면 세지 못한 것이다 — 0 으로 단정하지 않는다. */
+      removalsJournaled: anyPromoted ? removals : null,
+      specCoverage: (() => {
+        const c: any = snapshot ? readSpecCoverage(snapshot) : null
+        if (!c?.operations?.length) return null
+        const total = c.operations.length
+        const declared = c.operations.filter((o: any) => o.duration === 'declared' || o.duration === 'measured').length
+        return { declared, total }
+      })(),
+      forecastRan: null, // 예측 실행 이력을 남기는 자리가 아직 없다 — 모른다고 말한다
+      feed: 'unknown'
+    }
+
+    const assessment = assessSuite(facts)
+    return { instanceId, ...assessment, spec: SUITE_SPEC, facts }
+  }
+}

package/server/service/twin-space/twin-space-resolver.ts

@@ -1,3 +1,4 @@
+import { twinError } from '../../engine/log.js'
 import { Arg, Ctx, Mutation, Query, Resolver, Directive} from 'type-graphql'
 
 import { ScalarObject, getRepository } from '@things-factory/shell'
@@ -102,9 +103,9 @@ export class TwinSpaceResolver {
    * 공간 삭제 — **이 공간의 트윈이 있으면 거절한다.** 그래서 트윈이 현장을 잃는 일은 없다.
    *
    * ── 왜 모양을 바꿨나 (2026-08-13) ────────────────────────────────────────
-   * 예전에는 `Boolean` 을 돌려주고 거절은 **한국어 문장을 던졌다.** 두 가지가 틀렸다:
+   * 예전에는 `Boolean` 을 돌려주고 거절은 **한국어 문장을 냈다.** 두 가지가 틀렸다:
    *  ① 서버가 화면의 말을 정했다 — 일본어·스페인어 사용자에게 한국어가 새어 나간다.
-   *  ② 던진 예외를 화면이 받지 않아 **아무 일도 없는 것처럼** 보였다. 사용자는 삭제를 눌렀고
+   *  ② 오류를 낸 예외를 화면이 받지 않아 **아무 일도 없는 것처럼** 보였다. 사용자는 삭제를 눌렀고
    *     화면은 그대로였다. 거절을 조용히 하는 것은 실패보다 나쁘다.
    * 이제 `{ok, errorCode, errorParams}` 로 낸다 — 화면이 `twin.compose.del.<code>` 로 말을 만든다.
    */
@@ -220,7 +221,7 @@ export class TwinSpaceResolver {
         } as any)
       )
     } catch (err) {
-      console.error(`[twin-space] move audit not recorded for "${instanceId}"`, err)
+      twinError(`[twin-space] move audit not recorded for "${instanceId}"`, err)
     }
 
     return { ok: true, warnings: judgement.warnings }
@@ -285,7 +286,7 @@ export class TwinSpaceResolver {
         } as any)
       )
     } catch (err) {
-      console.error(`[twin-space] detach audit not recorded for "${instanceId}"`, err)
+      twinError(`[twin-space] detach audit not recorded for "${instanceId}"`, err)
     }
 
     return { ok: true, warnings: judgement.warnings }

package/shared/entity-delta.ts

@@ -72,7 +72,7 @@ const EXCLUDED = new Set(['id', 'epc', 'oee'])
 
 /**
  * OEE 원시 비율/카운트 → 표시용 정수 퍼센트 + 카운트.
- * 원시 누적 ms(idleMs 등)는 매 delta 증가해 무변화-생략을 무력화하므로 제외(유휴 자원의 매초 재방송 억제).
+ * 원시 누적 ms(idleMs 등)는 매 delta 증가해 무변화-생략을 무력화하므로 제외(유휴 자원의 매초 재브로드캐스팅 억제).
  * oee 미측정이면 undefined.
  */
 function shapeOee(o: any): any {
@@ -119,11 +119,11 @@ function aggregateItem(entity: any, idKey: 'id' | 'epc'): any {
 }
 
 /**
- * 물품 집약의 상한 — 큰 현장은 물품이 수만 개라, 전량을 매 방송에 실으면 전달이 현장을 느리게 한다.
+ * 물품 집약의 상한 — 큰 현장은 물품이 수만 개라, 전량을 매 브로드캐스팅에 실으면 전달이 현장을 느리게 한다.
  *
  * **조용히 자르지 않는다**: 넘치면 `total`(전체 수)과 `truncated`(잘린 수)를 함께 실어, 소비처가
  * "이게 전부" 라고 오해하지 않게 한다. 개별 물품은 태그별 delta 로 따로 나가고 그쪽은 시그니처 dedup
- * 이 걸려 **변한 것만** 재방송된다.
+ * 이 걸려 **변한 것만** 재브로드캐스팅된다.
  */
 export const ITEMS_AGGREGATE_LIMIT = 500
 
@@ -171,7 +171,28 @@ function energyByLocation(state: any): Map<string, Record<string, unknown>> {
   return out
 }
 
-export function buildEntityDeltas(state: any, instanceId: string): EntityDelta[] {
+/**
+ * 물품 축만 **범위를 줄일 수 있다** (2026-08-21).
+ *
+ * ── 왜 이 인자가 생겼나 ─────────────────────────────────────────────────────
+ * 브로드캐스팅 한 번이 만드는 payload 는 엔티티 수만큼이고 그 대부분이 물품이다(실측: 엔티티 3,611 중
+ * 물품 2,400 · 만드는 데 1.8ms · 문자열로 바꾸는 데 1.0ms). 바뀐 것이 물품 하나여도 전부 만들어
+ * 「같다」를 확인하고 버렸다.
+ *
+ * `items` 를 주면 **그 태그의 물품만** 개별 payload 를 만든다. 주지 않으면(`undefined`) 전부 만든다 —
+ * 부르는 쪽이 무엇이 바뀌었는지 말할 수 없을 때의 답이다.
+ *
+ * **집약 뷰는 범위를 받지 않는다.** 집약은 목록 전체가 한 payload 라서, 한 물품이 바뀌면 그 payload 는
+ * 통째로 새로 만들어야 한다(상한 500으로 이미 묶여 있다). 자리·설비·인원·자산·작업·오더도 범위를 받지
+ * 않는다 — 수가 적고, 잘못 걸러서 잃는 것이 크다(자리 점유는 물품이 떠난 자리와 도착한 자리가 함께
+ * 바뀌는데 사건은 한 지점만 말한다).
+ */
+export interface EntityDeltaScope {
+  /** 개별 payload 를 만들 물품 태그. 없으면 전부. */
+  items?: ReadonlySet<string>
+}
+
+export function buildEntityDeltas(state: any, instanceId: string, scope?: EntityDeltaScope): EntityDelta[] {
   const out: EntityDelta[] = []
   const locEnergy = energyByLocation(state)
 
@@ -203,8 +224,11 @@ export function buildEntityDeltas(state: any, instanceId: string): EntityDelta[]
     out.push({ tag: t.id, data: payloadOf('task', t) })
   }
   for (const it of state?.items ?? []) {
-    /* 물품의 태그는 epc(개체 식별자) — 노드·무버와 달리 id 가 아니다. */
-    if (it?.epc) out.push({ tag: it.epc, data: payloadOf('item', it) })
+    /* 물품의 태그는 epc(개체 식별자) — 자리·설비와 달리 id 가 아니다. */
+    if (!it?.epc) continue
+    /* 범위가 주어졌으면 그 안의 물품만 만든다 — 나머지는 값이 그대로이므로 보낼 것이 없다. */
+    if (scope?.items && !scope.items.has(it.epc)) continue
+    out.push({ tag: it.epc, data: payloadOf('item', it) })
   }
 
   /* ── 집약 뷰 ──────────────────────────────────────────────────────────────
@@ -274,7 +298,7 @@ export function buildEntityDeltas(state: any, instanceId: string): EntityDelta[]
         ...(energy.contractKW !== undefined ? { contractKW: energy.contractKW } : {}),
         ...(energy.open ? { open: energy.open } : {}),
         ...(energy.peakSince ? { peakSince: energy.peakSince } : {}),
-        /* 마감된 구간은 **최근 것만** 낸다 — 하루치를 매 방송에 실으면 채널이 그것으로 찬다.
+        /* 마감된 구간은 **최근 것만** 낸다 — 하루치를 매 브로드캐스팅에 실으면 채널이 그것으로 찬다.
            전체 수는 함께 낸다(조용히 자르지 않는다). */
         recent: (energy.closed ?? []).slice(-8),
         closedTotal: energy.closedTotal ?? 0

package/shared/kpi-broadcast.ts

@@ -1,7 +1,7 @@
 /*
  * 구간 성과 카드의 **대상 식별자**.
  *
- * 예전에는 이 파일이 방송 payload 도 만들었다(`shapeKpiBroadcast`). 2026-08-06 에 방송을 없애고 카드가
+ * 예전에는 이 파일이 브로드캐스팅 payload 도 만들었다(`shapeKpiBroadcast`). 2026-08-06 에 브로드캐스팅을 없애고 카드가
  * `twinKpi` 를 직접 묻게 바꿔서, 남은 것은 팔레트가 대상을 가리킬 때 쓰는 식별자뿐이다.
  * 왜 바꿨는지는 `twin-engine.ts` 의 주석과 `operato-twin/client/scene/twin-kpi-source.ts` 에 있다.
  */

package/shared/touched-items.ts

@@ -0,0 +1,73 @@
+/*
+ * 한 사건이 **어느 물품을 건드렸나** — 브로드캐스팅이 바뀐 것만 만들 수 있게. 순수(import 없음).
+ *
+ * ── 왜 물품만인가 (2026-08-21 실측) ─────────────────────────────────────────
+ * 브로드캐스팅 한 번이 만드는 payload 는 엔티티 수만큼이고, 그 대부분이 물품이다(실측: 엔티티 3,611 중
+ * 물품 2,400). 자리·설비·인원·자산은 모델이 정한 수라 적고(자리 최대 200, 평균 19), 작업·오더는 수백이다.
+ * 그래서 **물품 축만 걸러도** 만드는 양의 3분의 2가 사라진다.
+ *
+ * 나머지 축은 **매번 전부 만든다.** 걸러서 얻는 것이 적고, 잘못 걸러서 잃는 것이 크기 때문이다 —
+ * 예를 들어 물품이 한 자리에서 다른 자리로 가면 **두 자리의 점유가 함께 바뀌는데** EPCIS 사건은 읽은
+ * 지점 하나만 말한다. 그것으로 자리를 걸렀으면 떠난 자리의 점유가 낡은 값으로 남는다(오류 없이).
+ *
+ * ── 모르면 전부다 ───────────────────────────────────────────────────────────
+ * 이 함수가 `null` 을 돌려주면 「이 사건이 어느 물품을 건드렸는지 말할 수 없다」는 뜻이고, 그때 호출자는
+ * **전부 다시 만든다**(지금까지의 거동). 낯선 어휘가 오면 조용히 빠뜨리는 것이 아니라 비싸게 안전한
+ * 쪽으로 떨어진다 — 화면이 낡는 것보다 계산을 한 번 더 하는 것이 낫다.
+ */
+
+/** 물품 태그는 개체 식별자(epc)다 — 자리·설비와 달리 id 가 아니다(entity-delta 와 같은 규약). */
+function push(out: Set<string>, v: unknown): void {
+  if (typeof v === 'string' && v) out.add(v)
+}
+
+/**
+ * 물품을 건드리지 않는다고 **선언된** 사건들 — 커널의 운영 델타와 에너지 사건.
+ *
+ * 이 목록은 커널 계약(`OP_EVENT`·`ENERGY_EVENT`)에서 왔다. 여기 없는 낱말이 오면 「모른다」로 떨어져
+ * 전부 다시 만든다 — 커널이 사건을 늘렸을 때 조용히 빠뜨리는 대신 비싸게 안전한 쪽을 고른다.
+ *
+ * 근거: 미러의 리듀서에서 이 사건들은 작업·설비·인원·자산·오더·계량만 바꾼다(물품 축을 만지지 않는다).
+ * 자리 점유는 이 사건들도 바꾸지만, 자리는 **어차피 매번 전부 다시 만든다**(위 주석).
+ */
+const ITEM_FREE_EVENTS = new Set([
+  'task.status',
+  'equipment.status',
+  'person.status',
+  'asset.status',
+  'order.status',
+  'quality.output',
+  'attention.acked'
+])
+
+/**
+ * 이 사건이 건드린 물품 태그들. **말할 수 없으면 `null`** — 호출자는 그때 전부 다시 만든다.
+ *
+ * 개체를 말하는 자리를 전부 본다: `epcList`(관측·커미셔닝) · `parentID`(집약의 부모) ·
+ * `childEPCs`(집약의 자식) · `inputEPCList`·`outputEPCList`(변환의 입출력).
+ */
+export function touchedItemKeys(envelope: any): Set<string> | null {
+  const type = envelope?.eventType
+  if (typeof type !== 'string') return null
+  const d = envelope?.data ?? envelope
+  if (!d || typeof d !== 'object') return null
+
+  if (type.startsWith('energy.') || ITEM_FREE_EVENTS.has(type)) return new Set()
+  /* EPCIS 밖의 낯선 낱말 — 무엇을 바꿨는지 우리가 모른다. */
+  if (!type.startsWith('epcis.')) return null
+
+  const out = new Set<string>()
+  for (const v of d.epcList ?? []) push(out, v)
+  for (const v of d.childEPCs ?? []) push(out, v)
+  for (const v of d.inputEPCList ?? []) push(out, v)
+  for (const v of d.outputEPCList ?? []) push(out, v)
+  push(out, d.parentID)
+
+  /*
+   * 개체를 하나도 말하지 않은 EPCIS 사건은 **부류 수량**으로 말한 것이다(`quantityList`). 그 부류의
+   * 물품이 어느 것인지는 여기서 알 수 없으므로 전부 다시 만든다.
+   */
+  if (!out.size) return null
+
+  return out
+}

package/test/axis-journal-evidence.test.ts

@@ -0,0 +1,71 @@
+/*
+ * 상태가 빈 축의 이유 — **「아직 없다」와 「왔는데 상태에 없다」를 가른다** (2026-08-22).
+ *
+ * ── 무엇이 있었나 ───────────────────────────────────────────────────────────
+ * 카드가 「작업 — 아직 하나도 없습니다」라고 말했다. 그 트윈의 저널에는 `task.status` 5,786건이 있었고
+ * **마지막 상태가 `in-progress`** 였다. 사용자가 「작업 지시 835건인데 작업이 0인 이유」를 물었고,
+ * 원인은 관측 모드 커널이 관측기의 작업을 스냅샷으로 내보내지 않는 것이었다(커널 자리, 그 레인에 넘겼다).
+ *
+ * **화면 몫은 단정하지 않는 것이다.** 「아직 하나도 없습니다」는 「선언은 있고 사실이 아직 일어나지
+ * 않았다」는 뜻인데 실제로는 「사실이 일어났는데 상태에 오지 못했다」였다. 그 차이를 화면이 말하지
+ * 않아서 사용자가 직접 조사해야 했다.
+ *
+ * 이 시험이 지키는 것:
+ *  ① 저널에 그 축의 사건이 있으면 **그렇게 말한다**.
+ *  ② 없으면 예전 그대로 「아직 없다」다.
+ *  ③ 판단할 수 없는 축은 **아무 말도 만들지 않는다**(`null`) — 모르는 것을 새 사실로 바꾸지 않는다.
+ *  ④ 한 건만 묻는다 — 세는 것도 비용이다(저널 358만 행에서 전량 세기는 5.32초였다).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { axisSeenInJournal } from '../server/service/twin-model/axis-journal-evidence.ts'
+
+/** 저장소 흉내 — 어떤 조건으로 몇 번 물었는지 기록한다. */
+function repoWith(present: string[]) {
+  const asked: any[] = []
+  return {
+    asked,
+    async find(opts: any) {
+      asked.push(opts)
+      const t = opts?.where?.eventType
+      const hit =
+        typeof t === 'string'
+          ? present.includes(t)
+          : /* Like(…) 객체 — 접두사로 본다 */
+            present.some(p => p.startsWith(String(t?._value ?? '').replace('%', '')))
+      return hit ? [{ id: 'x' }] : []
+    }
+  } as any
+}
+
+const WHERE = { domain: { id: 'd' }, instanceId: 'twin-1' }
+
+test('저널에 그 축의 사건이 있으면 그렇게 말한다 — 작업', async () => {
+  const repo = repoWith(['task.status'])
+  assert.equal(await axisSeenInJournal(repo, WHERE, 'tasks'), true)
+})
+
+test('없으면 예전 그대로 — 아직 없다', async () => {
+  const repo = repoWith(['order.status'])
+  assert.equal(await axisSeenInJournal(repo, WHERE, 'tasks'), false)
+})
+
+test('물품은 사건 이름이 여럿이라 접두사로 본다 — 커널이 이름을 늘려도 낡지 않게', async () => {
+  const repo = repoWith(['epcis.AggregationEvent'])
+  assert.equal(await axisSeenInJournal(repo, WHERE, 'items'), true)
+})
+
+test('판단할 수 없는 축은 아무 말도 만들지 않는다', async () => {
+  const repo = repoWith(['task.status'])
+  assert.equal(await axisSeenInJournal(repo, WHERE, 'locations'), null, '표에 없는 축은 모른다')
+  assert.equal(repo.asked.length, 0, '모르는 축을 두고 저널을 묻지 않는다')
+})
+
+test('한 건만 묻는다 — 세는 것도 비용이다', async () => {
+  const repo = repoWith(['task.status'])
+  await axisSeenInJournal(repo, WHERE, 'tasks')
+  assert.equal(repo.asked.length, 1)
+  assert.equal(repo.asked[0].take, 1, '한 건만 읽는다')
+  assert.deepEqual(repo.asked[0].select, ['id'], '키 컬럼만 읽는다(행 본문을 만들지 않는다)')
+})