@things-factory/headless-twin 10.0.4 → 10.0.6

package/server/index.ts

@@ -4,6 +4,7 @@ export * from './service/index.js'
 import './routes.js'
 
 import { TwinEngine } from './engine/index.js'
+import { backfillTwinEventKeys } from './service/twin-event/backfill-keys.js'
 
 /* 모듈 부팅 — 영속 인스턴스 복구 훅(향후). 지금은 명시 start(mutation/부팅 설정)로 인스턴스 생성. */
 process.on('bootstrap-module-start' as any, async ({ app, config, client }: any) => {
@@ -13,4 +14,12 @@ process.on('bootstrap-module-start' as any, async ({ app, config, client }: any)
   } catch (ex) {
     console.error('Headless Twin host failed to start.', ex)
   }
+
+  /*
+   * 승격 검색 키 백필 — 컬럼이 생기기 전에 쌓인 저널을 채운다. 멱등·재개 가능이라 매 기동 불러도
+   * 채울 게 없으면 조각 한 번 읽고 끝난다(로그도 남기지 않는다).
+   * 기동을 막지 않는다 — 저널이 크면 오래 걸릴 수 있고, 그동안 트윈은 정상 동작해야 한다.
+   * 실패해도 서비스는 계속된다: 못 채운 만큼 **과거 이력 검색이 덜 나올 뿐**이므로 조용히 삼키지 않고 알린다.
+   */
+  backfillTwinEventKeys().catch(ex => console.error('twin-event key backfill failed — search over older journal rows will be incomplete.', ex))
 })

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

@@ -0,0 +1,72 @@
+import { IsNull } from 'typeorm'
+
+import { getRepository } from '@things-factory/shell'
+
+import { TwinEvent } from './twin-event.js'
+import { twinEventKeys } from './twin-event-keys.js'
+
+/*
+ * 승격 검색 키 백필 — 컬럼이 생기기 **전에** 쌓인 저널 행을 채운다.
+ *
+ * 이게 없으면 검색은 "오늘부터의 이력" 만 찾는다. 사용자에게는 그냥 **과거가 없는 것으로 보이고**,
+ * 그건 이번에 고치려던 결함(조용히 빠진 데이터)과 정확히 같은 종류다.
+ *
+ * 성질:
+ *  · 멱등 — 이미 채워진 행은 건드리지 않는다(bizStep IS NULL 인 것만 집는다).
+ *  · 재개 가능 — 중간에 죽어도 다음 기동에서 남은 것부터 이어간다.
+ *  · 조각내서 — 한 번에 다 읽지 않는다. 저널은 크다는 전제로 만든다.
+ *  · payload 는 손대지 않는다 — 정본은 그대로 두고 파생 색인만 채운다.
+ *
+ * 아주 큰 운영 저널이라면 기동 시 백그라운드보다 **마이그레이션으로 한 번** 도는 편이 낫다.
+ * 이 함수를 그대로 부르면 되므로 경로는 하나다.
+ */
+
+const CHUNK = 1000
+
+export interface BackfillResult {
+  /** 실제로 갱신한 행 수. */
+  updated: number
+  /** 훑었지만 payload 가 없어 채울 수 없던 행 수 — 0 이 아니면 인제스트 쪽을 봐야 한다. */
+  skipped: number
+}
+
+/**
+ * 남은 행을 전부 채운다. 진행 상황을 로그로 남긴다 — 조용히 오래 도는 작업은
+ * 멈춘 것과 구분되지 않는다.
+ */
+export async function backfillTwinEventKeys(): Promise<BackfillResult> {
+  const repo = getRepository(TwinEvent)
+  let updated = 0
+  let skipped = 0
+  let round = 0
+
+  for (;;) {
+    /* bizStep 은 이벤트 타입에서라도 유추되므로 **정상 인제스트라면 반드시 채워진다** —
+     * 즉 NULL 은 "승격 이전 행" 의 확실한 표식이다. epc 로 판정하면 품목 없는 이벤트를
+     * 매번 다시 집어 무한히 돈다. */
+    const rows = await repo.find({ where: { bizStep: IsNull() }, take: CHUNK, order: { revision: 'ASC' } })
+    if (rows.length === 0) break
+
+    const dirty: TwinEvent[] = []
+    for (const row of rows) {
+      if (!row.payload) {
+        skipped++
+        continue
+      }
+      Object.assign(row, twinEventKeys(row.payload))
+      dirty.push(row)
+    }
+    if (dirty.length) await repo.save(dirty, { chunk: 500 })
+    updated += dirty.length
+
+    /* payload 가 없는 행만 남으면 같은 조각을 영원히 다시 읽는다 — 진도가 없으면 멈춘다. */
+    if (dirty.length === 0) break
+
+    if (++round % 10 === 0) console.log(`[twin-event backfill] ${updated} rows filled…`)
+  }
+
+  if (updated || skipped) {
+    console.log(`[twin-event backfill] done — ${updated} filled, ${skipped} skipped (no payload)`)
+  }
+  return { updated, skipped }
+}

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

@@ -0,0 +1,102 @@
+/*
+ * 저널 검색 키 추출 — **순수**. 인제스트가 기록할 때 한 번 뽑아 인덱스 가능한 실컬럼으로 승격한다.
+ *
+ * ── 왜 승격하는가 ───────────────────────────────────────────────────────────
+ * 사용자가 저널에서 실제로 찾는 것은 "이 팔레트의 이력", "이 오더가 어디까지 갔나", "이 도크에서
+ * 무슨 일이 있었나" 다. 그런데 그 값들은 전부 `payload`(simple-json = TEXT) **안**에 있었다.
+ * things-factory 는 5개 DB 드라이버를 지원해야 해서 DB별 JSON 연산자를 쓸 수 없다 —
+ * 즉 승격 없이는 **어떤 방법으로도 서버에서 그 조건으로 거를 수 없었다**. 클라이언트가 받아온
+ * 몇 천 건 안에서만 찾는 시늉이 최선이었고, 저널이 커질수록 그 시늉은 거짓말에 가까워진다.
+ *
+ * 그래서 검색 축이 되는 값만 골라 컬럼으로 꺼낸다. payload 는 그대로 둔다(정본은 여전히 payload —
+ * 이건 파생 색인이지 새로운 진실이 아니다).
+ *
+ * ── 왜 여기(순수 모듈)인가 ──────────────────────────────────────────────────
+ * 기록 경로가 둘이다(`persistBatch` 라이브 벌크 · `persist` 심 단건). 두 곳에 각자 적으면
+ * 반드시 어긋나고, 어긋난 색인은 "없는 것처럼 보이는 이벤트" 를 만든다 — 저널에서 가장 나쁜 결함이다.
+ */
+
+/** 승격된 검색 키 — 전부 선택적. 뽑히지 않으면 **빈 문자열이 아니라 undefined**(결측≠빈값). */
+export interface TwinEventKeys {
+  bizStep?: string
+  epc?: string
+  orderId?: string
+  locationId?: string
+  moverId?: string
+}
+
+/*
+ * 컬럼 길이 상한. GS1 식별자(EPC URN·GDTI·SGLN)는 규격상 이보다 훨씬 짧다.
+ * 넘치는 값이 오면 **조용히 자르지 않고** 경고를 남긴다 — 색인이 원본과 다르면 검색 결과가 거짓이 되는데,
+ * 그 사실이 어디에도 안 남으면 아무도 모른다.
+ */
+const MAX_KEY = 255
+
+function clip(v: unknown, field: string): string | undefined {
+  if (v === undefined || v === null) return undefined
+  const s = String(v)
+  if (!s) return undefined
+  if (s.length <= MAX_KEY) return s
+  console.warn(
+    `[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)}…)`
+  )
+  return s.slice(0, MAX_KEY)
+}
+
+/** CBV bizStep URN 의 끝마디. 없으면 이벤트 타입에서 유추(`epcis.` 접두 제거). */
+export function bizStepOf(envelope: any): string | undefined {
+  const d = envelope?.data ?? envelope ?? {}
+  const tail = String(d.bizStep ?? '').split(':').pop()
+  return tail || String(envelope?.eventType ?? '').replace('epcis.', '') || undefined
+}
+
+/**
+ * 품목 식별자 — **전체 값**을 저장한다(끝마디만 저장하지 않는다).
+ *
+ * 표시용 축약은 화면이 하고, 색인은 원본을 갖는다. `search` 는 부분일치(contains)라
+ * 전체를 저장해 두면 끝마디("402.2")로도 URN 전체로도 찾힌다. 반대로 끝마디만 저장하면
+ * URN 으로 찾는 경로가 사라진다.
+ */
+export function epcOf(envelope: any): string | undefined {
+  const d = envelope?.data ?? envelope ?? {}
+  return d.epcList?.[0] ?? d.parentID ?? d.quantityList?.[0]?.epcClass ?? undefined
+}
+
+/** 거래 식별자(PO/SO) — EPCIS bizTransactionList 우선, 운영 델타는 `order`. */
+export function orderOf(envelope: any): string | undefined {
+  const d = envelope?.data ?? envelope ?? {}
+  return d.bizTransactionList?.[0]?.bizTransaction ?? d.order ?? undefined
+}
+
+/**
+ * 위치 — EPCIS 는 읽은 지점(readPoint) 우선, 없으면 업무 위치(bizLocation).
+ * 운영 델타(무버 이동 등)는 그 둘이 없고 평범한 `location` 을 쓴다 — 빠뜨리면 설비가 어디서
+ * 무엇을 했는지가 위치 축에서 통째로 사라진다.
+ */
+export function locationOf(envelope: any): string | undefined {
+  const d = envelope?.data ?? envelope ?? {}
+  return d.readPoint?.id ?? d.bizLocation?.id ?? d.location ?? undefined
+}
+
+/**
+ * 설비·무버 — 운영 델타(equipment.status·task.status)가 대상을 가리키는 축.
+ *
+ * EPCIS 어휘가 아니라서 다른 축 어디에도 안 잡힌다. 이게 없으면 "이 지게차가 오늘 무엇을 했나" 를
+ * 서버에서 물을 방법이 없어, 화면이 저널을 통째로 받아 훑는 수밖에 없다.
+ */
+export function moverOf(envelope: any): string | undefined {
+  const d = envelope?.data ?? envelope ?? {}
+  return d.moverId ?? undefined
+}
+
+/** 한 이벤트에서 승격 키 전부 — 기록 경로가 이 함수 하나만 부른다. */
+export function twinEventKeys(envelope: any): TwinEventKeys {
+  return {
+    bizStep: clip(bizStepOf(envelope), 'bizStep'),
+    epc: clip(epcOf(envelope), 'epc'),
+    orderId: clip(orderOf(envelope), 'orderId'),
+    locationId: clip(locationOf(envelope), 'locationId'),
+    moverId: clip(moverOf(envelope), 'moverId')
+  }
+}

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

@@ -0,0 +1,27 @@
+import { Field, Int, ObjectType } from 'type-graphql'
+
+import { TwinEvent } from './twin-event.js'
+
+/*
+ * 저널 목록 반환형 — things-factory 표준 `{ items, total }`(AttributeSetList·DomainList 등과 동형).
+ *
+ * `total` 이 이 타입의 존재 이유다. 기존 `twinEvents` 는 배열만 돌려줘서 **화면이 자기가 전체를 받은
+ * 건지 잘린 건지 알 방법이 없었다** — 그래서 리스트가 조용히 잘린 채로 "이게 전부" 처럼 보였다.
+ * 총건수를 함께 주면 화면은 "48 / 12,904" 라고 정직하게 말할 수 있고, 사용자는 좁혀야 한다는 걸 안다.
+ */
+@ObjectType({ description: 'A page of twin journal events together with the total number of matching records.' })
+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
+
+  /*
+   * 다음 페이지 커서. 저널은 **머리에 계속 쌓이는 목록**이라 offset 으로 뒤를 읽으면
+   * 읽는 사이 들어온 이벤트만큼 밀려 본 행이 또 나오거나 못 본 행이 사라진다.
+   * 이 값을 그대로 다음 요청의 `pagination.after` 로 돌려주면 그 문제가 없다.
+   */
+  @Field({ nullable: true, description: 'Opaque cursor for the next page. Pass it back as pagination.after to continue exactly where this page ended, without the duplicate or skipped rows that offset paging produces on a journal that keeps growing at the head. Null when this page is the last one.' })
+  nextCursor?: string
+}

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

@@ -10,8 +10,28 @@ import { Domain, ScalarObject } from '@things-factory/shell'
  * payload 는 simple-json(멀티DB 이식 — postgres/mysql/sqlite/mssql/oracle 공통, DB-specific JSON 타입 금지).
  * (CLAUDE.md: 모든 @ObjectType/@Field 는 영문 description 필수.)
  */
+/*
+ * ── 인덱스 설계 (2026-07-31) ────────────────────────────────────────────────
+ * 이 표는 **인제스트 경로의 뜨거운 append-only 테이블**이다. 인덱스 하나하나가 쓰기 증폭이므로
+ * "있으면 좋을" 인덱스를 붙이지 않는다. 실제 질의 패턴에 대응하는 것만 둔다.
+ *
+ *  ix_0 (domain, instanceId, revision)            원장 기본 정렬·커서 페이징·replay(ASC 주사)
+ *  ix_1 (domain, instanceId, eventTime)           시각 커서(untilTime)·시간창 KPI — 거의 모든 조회가 탄다
+ *  ix_2 (domain, instanceId, eventType, revision) 타입 필터 + 정렬 동시 충족(스케줄 화면 task/equipment)
+ *  ix_3 (domain, instanceId, epc)                 "이 물건의 이력" — Entity360 의 본질 질문
+ *  ix_4 (domain, instanceId, orderId)             "이 오더가 어디까지 갔나"
+ *
+ * bizStep·locationId·moverId 는 컬럼만 두고 인덱스는 두지 않는다 — 한 트윈 안에서 카디널리티가
+ * 낮아(업무단계 몇 개, 위치 수백, 설비 수십) (domain,instanceId) 로 이미 좁혀진 뒤의 잔여 필터로
+ * 충분하고, 뜨거운 표에 인덱스를 더 얹을 값어치가 없다. 저널 하나가 아주 커져서 이 축들의 조회가
+ * 느려지면 그때 측정을 근거로 인덱스를 추가할 일이지, 지레 얹어 쓰기를 무겁게 할 일은 아니다.
+ */
 @Entity()
 @Index('ix_twin_event_0', (e: TwinEvent) => [e.domain, e.instanceId, e.revision], { unique: false })
+@Index('ix_twin_event_1', (e: TwinEvent) => [e.domain, e.instanceId, e.eventTime], { unique: false })
+@Index('ix_twin_event_2', (e: TwinEvent) => [e.domain, e.instanceId, e.eventType, e.revision], { unique: false })
+@Index('ix_twin_event_3', (e: TwinEvent) => [e.domain, e.instanceId, e.epc], { unique: false })
+@Index('ix_twin_event_4', (e: TwinEvent) => [e.domain, e.instanceId, e.orderId], { unique: false })
 @ObjectType({ description: 'Append-only twin event journal record (EPCIS event or operational delta).' })
 export class TwinEvent {
   @PrimaryGeneratedColumn('uuid')
@@ -45,6 +65,34 @@ export class TwinEvent {
   @Field({ nullable: true, description: 'Simulation event time (ISO 8601).' })
   eventTime?: string
 
+  /*
+   * ── 승격된 검색 축 ────────────────────────────────────────────────────────
+   * payload 안에 있던 값을 인제스트 시점에 꺼내 실컬럼으로 둔다(`twin-event-keys.ts` 가 단독 소유).
+   * payload 가 여전히 정본이고 이것들은 **파생 색인**이다 — 새로운 진실이 아니라 찾을 수 있게 하는 장치.
+   * simple-json(TEXT) 안의 값은 5개 DB 드라이버 공통으로 거를 방법이 없어서(멀티DB 호환 규칙상
+   * DB별 JSON 연산자 금지) 승격 외의 선택지가 없다.
+   * 길이 상한 255 는 GS1 식별자 규격 대비 충분하며, 넘치는 값은 조용히 잘리지 않고 경고를 남긴다.
+   */
+  @Column({ length: 255, nullable: true })
+  @Field({ nullable: true, description: 'Business step (CBV bizStep tail), promoted from the payload for indexed filtering.' })
+  bizStep?: string
+
+  @Column({ length: 255, nullable: true })
+  @Field({ nullable: true, description: 'Item identifier (EPC / EPC class / parent id), promoted from the payload for indexed lookup of one item history.' })
+  epc?: string
+
+  @Column({ length: 255, nullable: true })
+  @Field({ nullable: true, description: 'Business transaction identifier (PO / SO), promoted from the payload for indexed lookup of one order history.' })
+  orderId?: string
+
+  @Column({ length: 255, nullable: true })
+  @Field({ nullable: true, description: 'Location identifier (read point, business location, or the plain location an operational delta carries), promoted from the payload for indexed filtering.' })
+  locationId?: string
+
+  @Column({ length: 255, nullable: true })
+  @Field({ nullable: true, description: 'Equipment or mover identifier carried by operational deltas, promoted from the payload so one machine history can be asked for on the server.' })
+  moverId?: string
+
   @Column({ type: 'simple-json', nullable: true })
   @Field(type => ScalarObject, { nullable: true, description: 'Raw canonical envelope (EPCIS event or operational delta) as JSON.' })
   payload?: any

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

@@ -1,10 +1,12 @@
 import { Between, LessThanOrEqual, MoreThanOrEqual } from 'typeorm'
-import { Arg, Ctx, Int, Query, Resolver } from 'type-graphql'
+import { Arg, Args, Ctx, Int, Query, Resolver } from 'type-graphql'
 
-import { getRepository, ScalarObject } from '@things-factory/shell'
+import { buildNextCursor, cursorSortings, getQueryBuilderFromListParams, getRepository, ListParam, ScalarObject } from '@things-factory/shell'
 
 import { TwinEvent } from '../twin-event/twin-event.js'
+import { TwinEventList } from '../twin-event/twin-event-type.js'
 import { TwinEngine } from '../../engine/index.js'
+import { computeTwinKpi, resolveTwinTargets } from '../../engine/kpi-query.js'
 
 /*
  * 저널 읽기 채널 — 상향 query.
@@ -38,6 +40,138 @@ export class TwinJournalQuery {
     return getRepository(TwinEvent).find({ where, order: { revision: 'DESC' }, take: limit ?? 200 })
   }
 
+  /**
+   * 저널 목록 — things-factory 표준 목록 계약(`ListParam` → `{ items, total }`).
+   *
+   * ── 왜 `twinEvents` 와 따로 두는가 ─────────────────────────────────────────
+   * `twinEvents` 는 배열만 돌려준다. 화면은 자기가 받은 게 전부인지 잘린 건지 알 수 없었고, 그래서
+   * 리스트가 **조용히 잘린 채 "이게 전부" 처럼** 보였다(원장 limit 120 이 대표적). 총건수를 함께
+   * 주면 "48 / 12,904" 라고 말할 수 있고, 사용자는 좁혀야 한다는 사실을 안다.
+   * 기존 호출자를 깨지 않으려고 `twinEvents` 는 그대로 두고 목록 계약을 새로 연다.
+   *
+   * ── 검색이 진짜인 이유 ─────────────────────────────────────────────────────
+   * `searchables` 는 전부 **인덱스 가능한 승격 컬럼**이다(payload JSON 안이 아니라). 프레임워크
+   * 질의 빌더는 `searchables` 에 없는 컬럼의 LIKE 를 경고 후 무시한다 — 인덱스 없는 전체 스캔을
+   * 막기 위해서다. 그 규율에 맞추려고 검색 축을 컬럼으로 승격했다(`twin-event-keys.ts`).
+   *
+   * 정렬 기본값은 revision DESC(최신순) — 저널의 자연 순서이자 ix_twin_event_0 가 그대로 타는 축.
+   */
+  @Query(returns => TwinEventList, {
+    description:
+      'List twin journal events with the standard list contract (filters, pagination, sortings) plus the total match count. ' +
+      'Scope is either one twin (instanceId) or a whole site (spaceId, which folds in every running operational twin co-located there, the same targets twinKpi uses) — one of the two is required. ' +
+      'Searchable fields are the columns promoted out of the payload: epc (item), orderId, locationId, moverId (equipment), bizStep, eventType. ' +
+      'Returns total so a caller can show an honest "shown of total" count instead of silently truncating a long journal. ' +
+      'Defaults to newest first (revision descending) and to a page of 100; limit is capped at 500 per page.'
+  })
+  async twinEventList(
+    @Args(type => ListParam) params: ListParam,
+    @Ctx() context: ResolverContext,
+    @Arg('instanceId', { nullable: true, description: 'Read one twin instance journal.' }) instanceId?: string,
+    @Arg('spaceId', { nullable: true, description: 'Read every running operational twin co-located in this space, merged on the shared time axis.' }) spaceId?: string
+  ): Promise<TwinEventList> {
+    const { domain } = context.state
+    if (!instanceId && !spaceId) throw new Error('either instanceId or spaceId is required')
+    /* 테넌트 격리 — twinKpi 와 같은 규약. 남의 트윈은 빈 결과가 아니라 명시 실패로 알린다
+     * (조용한 빈 목록은 "권한 없음" 과 "데이터 없음" 을 구분할 수 없게 만든다). */
+    if (instanceId && !TwinEngine.owns(domain.id, instanceId)) {
+      throw new Error(`twin instance not found in this tenant: ${instanceId}`)
+    }
+
+    /* 대상 해소는 KPI 와 같은 창구를 쓴다 — 같은 공간을 보면서 화면마다 대상이 달라지면 안 된다. */
+    const instanceIds = await resolveTwinTargets(domain.id, instanceId, spaceId)
+    if (instanceIds.length === 0) return { items: [], total: 0 }
+
+    /* 페이지 상한 — 화면이 실수로(또는 악의로) 저널 전체를 한 번에 달라고 해도 서버가 버틴다. */
+    const limit = Math.min(params.pagination?.limit ?? 100, 500)
+    const effective: ListParam = {
+      ...params,
+      pagination: { page: params.pagination?.page ?? 1, limit },
+      /* 기본 정렬은 시각 내림차순 — 여러 트윈을 합칠 때 공통 축은 revision(트윈별 카운터)이 아니라
+       * **시각**이다. revision 으로 섞으면 서로 다른 트윈의 무관한 카운터가 뒤엉킨다. */
+      sortings: params.sortings?.length ? params.sortings : [{ name: 'eventTime', desc: true }]
+    }
+
+    const qb = getQueryBuilderFromListParams({
+      repository: getRepository(TwinEvent),
+      params: effective,
+      domain,
+      /* 전부 인덱스 가능한 승격 컬럼 — 자유 검색어는 서버가 이 축들로 펼친다. */
+      searchables: ['epc', 'orderId', 'locationId', 'moverId', 'bizStep', 'eventType'],
+      /* 정렬은 인덱스가 받쳐 주는 축으로만 — 큰 저널에서 임의 컬럼 정렬은 전체 정렬 스캔이다. */
+      sortables: ['eventTime', 'revision', 'eventType', 'bizStep'],
+      defaultLimit: 100,
+      maxLimit: 500
+    })
+    /* 대상 범위는 호출자가 필터로 빼먹을 수 있는 값이 아니다 — 계약상 필수라 여기서 강제한다. */
+    qb.andWhere(`${qb.alias}.instanceId IN (:...instanceIds)`, { instanceIds })
+
+    const [items, total] = await qb.getManyAndCount()
+
+    /* 다음 커서는 **이번 페이지의 마지막 행**에서 만든다. 페이지가 상한보다 짧으면 뒤가 없다. */
+    const axes = cursorSortings(effective.sortings, 'id')
+    const nextCursor = items.length === limit ? buildNextCursor(items[items.length - 1], axes) : undefined
+
+    return { items, total, nextCursor }
+  }
+
+  /**
+   * 업무 KPI — 시간창 처리량·소요시간·자원 점유. 저널을 **접어서** 만든다(새 계측을 심지 않는다).
+   *
+   * `twinMetrics`(초당 이벤트 수 = 인프라 부하)와 **다른 것**이다: 이건 "지난 한 시간에 몇 건 처리했고
+   * 한 건에 얼마나 걸렸나" 다. 이름이 비슷해 헷갈리기 쉬우므로 설명에 명시한다.
+   *
+   * 완료된 작업의 **시작 이벤트가 창 앞에 있을 수 있어** 조회 구간을 창보다 앞으로 넓힌다(lookback).
+   * 그래도 못 찾은 것은 결과의 `unpaired` 로 드러난다 — 평균에서 조용히 빠지면 지표가 거짓이 된다.
+   */
+  @Query(returns => ScalarObject, {
+    description:
+      'Windowed business KPI folded from the event journal, for one space (every running twin in it, folded together — averaging per-twin percentiles would be wrong) or one twin: throughput (completed tasks / orders), lead / work / wait time distributions (p50·p90), and per-resource busy ratio. Distinct from twinMetrics, which reports infrastructure throughput (events per second). When toTime is omitted the window ends at the twin\'s own last recorded event time, not wall clock — a simulated twin lives on its own clock, so asking for \'the last hour\' in real time would always find nothing. The basis used is reported in window.basis. Pass groupBy (resource | taskKind | node | order | area) to break the same window down by that perspective — per-group numbers use the same rules as the totals, so group counts sum to the total, and groups beyond groupLimit are reported as groups.truncated (how many groups) and groups.truncatedTasks (how much work those groups held) rather than silently dropped. Pass compareTo (previous | yesterday) to fold the same-length window shifted back and get comparison.delta (current minus that window); when the comparison window has no records, comparison.measured is false and no delta is produced rather than reporting zero change. Passing groupBy together with compareTo crosses the two: each group carries prevTasks / deltaTasks / deltaWorkP50Ms, groups absent from the comparison window are flagged isNew (no delta, so growth is not implied), and groups that had work before but none now are returned in groups.disappeared so a stopped area is never silently missing from the table. Area breakdown needs board nodes to carry a parent area; when they do not, groups.note says so instead of implying there was no work. When the journal read hits its row cap, eventsCapped is true and every number is a lower bound — narrow the window and ask again rather than reading the smaller figures as a drop in performance. Completions are counted in the window they complete; starts are looked up before the window, and any completion whose start was not found is reported in `unpaired` rather than silently dropped.'
+  })
+  async twinKpi(
+    @Ctx() context: ResolverContext,
+    /* 공간이 사용자의 단위다 — 한 트윈만 보려면 instanceId 를 준다(둘 중 하나 필수). */
+    @Arg('spaceId', { nullable: true }) spaceId?: string,
+    @Arg('instanceId', { nullable: true }) instanceId?: string,
+    /** 창 시작·끝(ISO). 미지정이면 최근 1시간. */
+    @Arg('fromTime', { nullable: true }) fromTime?: string,
+    @Arg('toTime', { nullable: true }) toTime?: string,
+    /** 창 길이(분). fromTime 이 있으면 무시. 기본 60. */
+    @Arg('windowMinutes', type => Int, { nullable: true }) windowMinutes?: number,
+    /** 추세를 위해 창을 N 등분(1~48). 미지정이면 쪼개지 않는다. */
+    @Arg('buckets', type => Int, { nullable: true }) buckets?: number,
+    /** 시작 이벤트를 찾기 위해 창보다 앞으로 더 읽는 시간(분). 기본 60. */
+    @Arg('lookbackMinutes', type => Int, { nullable: true }) lookbackMinutes?: number,
+    /** 관점 축 — 같은 창을 자원별·작업종류별·도착지점별·오더별·구역별로 쪼갠다. */
+    @Arg('groupBy', { nullable: true }) groupBy?: string,
+    /** 축의 상한(기본 20, 최대 100). 넘치면 잘라내고 잘린 수를 알린다. */
+    @Arg('groupLimit', type => Int, { nullable: true }) groupLimit?: number,
+    /** 비교 기준 — 같은 길이의 앞 구간(previous)이나 하루 전 같은 시간(yesterday). */
+    @Arg('compareTo', { nullable: true }) compareTo?: string
+  ): Promise<any> {
+    /* 테넌트 격리 — 트윈 지정이면 소속을 확인한다. 공간 지정이면 대상 해소가 도메인 목록에서
+     * 이뤄지므로(computeTwinKpi) 남의 트윈이 섞이지 않는다. 조용한 빈 결과가 아니라 명시 실패. */
+    if (instanceId && !TwinEngine.owns(context.state.domain.id, instanceId)) {
+      throw new Error(`twin instance not found in this tenant: ${instanceId}`)
+    }
+    if (!instanceId && !spaceId) throw new Error('either spaceId or instanceId is required')
+    /* 창 해소·조회·폴드는 `computeTwinKpi` 가 소유한다 — 같은 규칙을 AI 도구와 공유해야 한다
+     * (두 곳에 적으면 화면과 AI 가 다른 숫자를 말한다). */
+    return computeTwinKpi({
+      domainId: context.state.domain.id,
+      instanceId,
+      spaceId,
+      fromTime,
+      toTime,
+      windowMinutes,
+      buckets,
+      lookbackMinutes,
+      groupBy: groupBy as any,
+      groupLimit,
+      compareTo: compareTo as any
+    })
+  }
+
   @Query(returns => ScalarObject, {
     nullable: true,
     description: 'Reconstruct twin state from the durable journal (DB → replay). untilTime (ISO) for time-travel on the shared clock (preferred); untilRevision for the lens-internal counter; omit both for latest.'