@things-factory/headless-twin 10.0.11 → 10.0.13

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/adopt-structure-live.test.ts

@@ -63,8 +63,8 @@ before(async () => {
   const d = await ds.getRepository(Domain).save({ name: 'adopt-test', subdomain: 'adopt-test' } as any)
   domainId = d.id
 
-  await TwinEngine.ingestMaster(domainId, master(MIRROR, 3, 2))
-  await TwinEngine.ingestMaster(domainId, master(SIM, 3, 2))
+  await TwinEngine.ingestMaster(domainId, master(MIRROR, 3, 2), 'reset')
+  await TwinEngine.ingestMaster(domainId, master(SIM, 3, 2), 'reset')
 })
 
 after(async () => {
@@ -74,10 +74,10 @@ after(async () => {
 
 test('돌고 있는 미러는 멈추지 않고 갈아탄다 — 세 층이 함께 움직인다', async () => {
   /* 미러 기동은 선언 기반 부팅이 가른다 — `startFromRegistry` 는 시뮬 경로다(같은 함수가 아니다). */
-  const rt = await TwinEngine.bootDeclared(domainId, MIRROR, 'mirror')
+  const rt = await TwinEngine.bootDeclared(domainId, MIRROR, 'resync')
   assert.equal(rt.mode, 'live', '미러로 떠야 이 검사가 뜻이 있다')
 
-  const res = await TwinEngine.ingestMaster(domainId, master(MIRROR, 7, 2))
+  const res = await TwinEngine.ingestMaster(domainId, master(MIRROR, 7, 2), 'reset')
 
   /* ① 리비전 — 이후 이벤트가 달고 다닐 번호가 올라간다 */
   const revs = await ds.getRepository(TwinStructure).find({ where: { instanceId: MIRROR }, order: { rev: 'ASC' } })
@@ -101,7 +101,7 @@ test('돌고 있는 미러는 멈추지 않고 갈아탄다 — 세 층이 함
 })
 
 test('사라진 설비를 수로 알린다 — 자리가 수천인 현장에서 직접 세어 보게 하지 않는다', async () => {
-  const res = await TwinEngine.ingestMaster(domainId, master(MIRROR, 7, 1)) // 지게차 2 → 1
+  const res = await TwinEngine.ingestMaster(domainId, master(MIRROR, 7, 1), 'reset') // 지게차 2 → 1
   const adopted = res.warnings.find((w: any) => w.code === 'structure-adopted')
   assert.equal(adopted.params.equipmentDropped, 1)
 
@@ -111,10 +111,10 @@ test('사라진 설비를 수로 알린다 — 자리가 수천인 현장에서
 })
 
 test('돌고 있는 시뮬레이션은 여전히 거절한다 — 조건이 바뀐 실험은 다른 실험이다', async () => {
-  await TwinEngine.bootDeclared(domainId, SIM, 'sim-experiment')
+  await TwinEngine.bootDeclared(domainId, SIM, 'reset')
   const before = (await ds.getRepository(TwinStructure).find({ where: { instanceId: SIM } })).length
 
-  await assert.rejects(() => TwinEngine.ingestMaster(domainId, master(SIM, 9, 2)), /is running/)
+  await assert.rejects(() => TwinEngine.ingestMaster(domainId, master(SIM, 9, 2), 'reset'), /is running/)
 
   assert.equal(
     (await ds.getRepository(TwinStructure).find({ where: { instanceId: SIM } })).length,

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'], '키 컬럼만 읽는다(행 본문을 만들지 않는다)')
+})

package/test/axis-read.test.ts

@@ -40,7 +40,7 @@ test('상태가 없으면 모른다 — 커널이 멈춰 있으면 0 이 아니
   assert.equal(axisValueOf(undefined, { axis: 'demandWindows', path: 'energy.closed' }), undefined)
 })
 
-test('경로 따라가기는 중간 부재에서 멈춘다 — 던지지 않는다', () => {
+test('경로 따라가기는 중간 부재에서 멈춘다 — 오류를 내지 않는다', () => {
   assert.equal(atPath({ a: { b: 1 } }, 'a.b'), 1)
   assert.equal(atPath({ a: null }, 'a.b'), undefined)
   assert.equal(atPath(undefined, 'a.b'), undefined)
@@ -85,3 +85,103 @@ test('커널 선언과 상태의 모양이 맞는다 — 선언한 경로에 정
   assert.equal(Array.isArray(windows), true, '선언한 경로에 목록이 있어야 한다')
   assert.equal(windows.length, 1, '마감된 구간 하나')
 })
+
+/*
+ * ── 규칙의 집이 하나인지 **기계가 지킨다** (2026-08-21) ──────────────────────
+ *
+ * 위 단위 시험은 처음부터 초록이었다. 함수는 옳았고, **호출부 하나가 그 함수를 지나지 않았다** —
+ * `twin-model-item-query.ts` 가 `(snap as any)[axis]` 로 축 이름을 직접 읽었다. 그래서 개념 지도의
+ * 카드는 수요 구간을 **42** 로 세는데 그 개념을 열면 **0건**이 나왔다. 사용자에게는 「트윈이 비어
+ * 있다」로 읽힌다.
+ *
+ * 그 함정은 형제 파일 주석에 이미 적혀 있었다(「축 이름으로만 읽으면 중첩된 축이 언제나 관측 없음이
+ * 된다 — 에너지의 수요 구간이 그렇다」). **적어 두는 것으로는 막히지 않았다.** 그래서 센다.
+ */
+import { readFileSync, readdirSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const SVC = fileURLToPath(new URL('../server/service/twin-model', import.meta.url))
+
+/**
+ * 상태에서 축을 **이름으로** 읽는 모양 — `snap[axis]` · `(state as any)[axis]` 류.
+ *
+ * 앞에 `\b` 를 둔다: 처음에는 없어서 `const` 안의 `st` 를 잡아 `ROW_BACKED[axis]`(조회표이지 상태
+ * 읽기가 아니다)를 위반으로 냈다. **거짓 빨강을 내는 가드는 없는 것보다 나쁘다** — 이름이 근거다.
+ */
+const BY_NAME = /\(?\s*\b(?:snap|state)\b[^)\n]*\)?\s*\[\s*axis\s*\]/g
+
+test('축을 이름으로 읽는 자리가 없다 — 선언된 경로를 지나야 중첩된 축이 보인다', () => {
+  const offenders: string[] = []
+  for (const f of readdirSync(SVC).filter(n => n.endsWith('.ts'))) {
+    const src = readFileSync(join(SVC, f), 'utf8')
+    for (const line of src.split('\n')) {
+      /* 주석은 규칙이 아니라 설명이다 — 함정을 적어 둔 줄이 스스로 위반으로 잡히면 신호가 묻힌다. */
+      const code = line.replace(/\/\*.*?\*\//g, '').replace(/\/\/.*$/, '')
+      if (code.trimStart().startsWith('*')) continue
+      if (BY_NAME.test(code)) offenders.push(`${f}: ${line.trim()}`)
+      BY_NAME.lastIndex = 0
+    }
+  }
+  assert.deepEqual(
+    offenders,
+    [],
+    `축을 이름으로 읽는 자리가 있다 — \`axisValueOf(state, 축선언)\` 을 쓰십시오.\n${offenders.join('\n')}`
+  )
+})
+
+test('수요 구간은 실제로 중첩된 축이다 — 이 가드가 지키는 대상이 있다', () => {
+  /* 가드가 지킬 것이 없으면 그 가드는 초록으로 거짓을 말한다. 대상이 실재하는지 함께 본다. */
+  const req = createRequire(import.meta.url)
+  const { TWIN_AXES } = req('@operato/twin-kernel')
+  const nested = (TWIN_AXES as any[]).filter(a => a.path)
+
+  assert.ok(nested.length > 0, '경로를 가진 축이 하나도 없으면 이 가드는 의미가 없다')
+  assert.ok(
+    nested.some(a => a.axis === 'demandWindows'),
+    `수요 구간이 경로 축이어야 한다 — 실제 경로 축: ${nested.map(a => a.axis).join(', ')}`
+  )
+})
+
+/*
+ * ── 무엇이 항목을 가리키는지도 **선언이 말한다** (2026-08-21) ─────────────────
+ *
+ * 개념 지도의 수요 구간을 열면 여섯 구간이 모두 「식별자 없음 — 참조할 수 없는 항목입니다」로 보였다.
+ * 값(구간 시작·종료·최대수요)은 실재하는데 **가리킬 수 없다고 말한 것**이다.
+ *
+ * 원인은 축이 사는 자리를 짐작했던 것과 **같은 부류**다: 소비처가 `id`·`key`·`gtin` 을 순서대로
+ * 짐작했고, 수요 구간에는 그 셋이 없다. 그것은 결함이 아니다 — 구간의 정체성은 **언제 시작했나**이고
+ * 커널도 그것으로 키를 만든다(`contract-projected-over:<startMs>`).
+ */
+test('id 가 없는 상태 축은 무엇이 항목을 가리키는지 선언한다', () => {
+  const req2 = createRequire(import.meta.url)
+  const { TWIN_AXES } = req2('@operato/twin-kernel')
+  const dw = (TWIN_AXES as any[]).find(a => a.axis === 'demandWindows')
+
+  assert.ok(dw, '수요 구간 축이 있어야 한다')
+  assert.equal(dw.idField, 'startMs', '구간의 정체성은 시작 시각이다')
+})
+
+test('항목 질의가 짐작하지 않는다 — 선언된 자리를 읽는다', () => {
+  /*
+   * 기계가 지킨다. 주석에 적어 두는 것으로는 막히지 않는 것을 오늘 이미 겪었다(축이 사는 자리를
+   * 짐작한 자리 셋이 형제 파일 주석의 경고에도 남아 있었다).
+   */
+  /*
+   * ── **파일 이름에 묶지 않는다** (2026-08-22) ────────────────────────────────
+   * 예전에는 `twin-model-item-query.ts` 하나만 읽었다. 다른 레인이 `idOf` 를 `name-index.ts` 로
+   * 옮기자(기능은 배열 차례까지 온전했다) 이 가드가 **거짓 빨강**을 냈다. 가드가 지켜야 하는 것은
+   * 「그 파일에 그 낱말이 있나」가 아니라 「**이 서비스 어딘가에서 선언된 식별 자리를 읽나**」다.
+   *
+   * 그래서 서비스 폴더를 훑는다 — 옮겨도 따라간다. 옮길 자유를 막는 가드는 사람을 가드와 싸우게 만든다.
+   */
+  const sources = readdirSync(SVC, { recursive: true } as any)
+    .filter((f: any) => String(f).endsWith('.ts'))
+    .map((f: any) => readFileSync(join(SVC, String(f)), 'utf8'))
+  const all = sources.join('\n')
+
+  assert.match(all, /idField/, '선언된 식별 자리를 읽어야 한다(이 서비스 어딘가에서)')
+  /* `x?.id === itemId` 로 찾던 자리가 남아 있으면 그 축의 항목은 열 수 없다. */
+  assert.doesNotMatch(all, /find\(\(x: any\) => x\?\.id === itemId\)/, 'id 로만 찾는 자리가 남지 않았다')
+})