@things-factory/headless-twin 10.0.15 → 10.0.17

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

@@ -73,7 +73,7 @@ export class TwinInstance {
    * 하나**였고, 그것은 원본의 성질이 아니라 **트윈과 자기 과거의 관계**다: 같은 시뮬레이터 원본을 보는 두
    * 트윈이 하나는 이어가고 하나는 매번 처음부터 재현할 수 있다. 그래서 축은 남고 이름만 바뀌었다.
    *
-   * **비어 있을 수 없고, 기본값도 없다.** 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로
+   * **비어 있을 수 없고, 기본값도 없다.** 예전에는 미선언이 알리지 않고 `sim-experiment`(=저널 초기화)로
    * 떨어졌다 — 값이 하나 어긋나는 순간 이력을 지우는 길이다. 이제 읽는 쪽이 **오류를 낸다**
    * (`engine/restart-policy.ts`). 선언은 프로비저닝하는 쪽의 몫이다.
    */
@@ -83,7 +83,7 @@ export class TwinInstance {
 
   /* 읽을 때 어휘 세대를 흡수한다(`nodes`/`movers`/`equipmentList` → `locations`/`equipment`).  (vocabulary-guard: allow — 세대 이름 없이는 설명할 수 없다.)
      자리마다 리더를 쓰게 하면 다음에 추가되는 자리가 또 빠지고, 빠진 것은 오류가 아니라 **빈 공장**이라
-     조용하다(2026-08-06: 모델러 엔티티 목록이 통째로 비었다). 상세 `engine/model-vocabulary.ts`. */
+     들어온 것이 없다(2026-08-06: 모델러 엔티티 목록이 통째로 비었다). 상세 `engine/model-vocabulary.ts`. */
   @Column({ type: 'simple-json', nullable: true, transformer: modelColumnTransformer })
   @Field(type => ScalarObject, { nullable: true, description: 'TwinModelDef blueprint (locations/equipment) required to replay events into state. Older stored boards used nodes/movers/equipmentList; they are normalised on read so consumers see one vocabulary.' }) // vocabulary-guard: allow — 옛 어휘를 흡수하는 것이 이 코드의 일이다(세대 이름을 적어야 흡수할 수 있다)
   model?: any
@@ -92,7 +92,7 @@ export class TwinInstance {
    * 로컬 선언 겹 — **구조는 원천이, 수는 우리가.**
    *
    * 요금 단가·계약 정보·축전지 충전율처럼 원 시스템이 모르는 값을 넣는 자리다. `model` 에 직접 쓰지
-   * 않는 이유는 그것이 **원천의 사본**이기 때문이다: 다시 읽기가 사본을 새로 그리면 직접 쓴 값은 조용히
+   * 않는 이유는 그것이 **원천의 사본**이기 때문이다: 다시 읽기가 사본을 새로 그리면 직접 쓴 값은 알리지 않고
    * 사라진다(요금이 사라지면 금액도 사라지고, 사용자는 이유를 알 수 없다).
    *
    * 그래서 여기 남기고, 모델을 그릴 때마다 그 위에 얹는다(`engine/local-declarations`). 얹힌 값에는
@@ -164,7 +164,7 @@ export class TwinInstance {
    * 이 세션에만 그 부류를 셋 겪었다(`model.operations` 두 집 · `materials` 두 집 · tenantId 중복).
    *
    * 복제한 값은 반드시 어긋난다 — 저널은 틱마다 늘고 이 컬럼은 저장할 때만 갱신되므로, 화면이
-   * 어느 쪽을 읽느냐로 다른 숫자가 나온다. 그 조용한 어긋남을 만들 이유가 없다.
+   * 어느 쪽을 읽느냐로 다른 숫자가 나온다. 그 들어온 것이 없는 어긋남을 만들 이유가 없다.
    */
 
   @CreateDateColumn()

package/server/service/twin-journal/event-type-split-shape.ts

@@ -0,0 +1,112 @@
+/*
+ * **이 물음이 「여러 종류를 시각순으로」인가** — 순수 판단만 여기 둔다.
+ *
+ * 데이터베이스를 부르지 않는다. 그래서 시험이 이 파일을 그대로 부를 수 있다(데코레이터가 없다).
+ * 판단이 조회 코드 안에 섞여 있으면 그 판단만 확인할 방법이 없고, 그러면 「어떤 물음이 나눠 묻는
+ * 갈래로 가는가」가 아무도 읽지 못하는 규칙이 된다.
+ *
+ * 실측 근거와 고침의 뜻은 `event-type-split.ts` 머리에 있다.
+ */
+import { absoluteTime } from '../../engine/read-time.js'
+
+/** 질의를 몇 개까지 나눌까 — 대상 × 종류. 이 이상이면 나누는 것이 손해다. */
+export const MAX_SPLIT = 24
+
+/** 종류 목록의 상한 — 이보다 많으면 「이 종류만」이 아니라 사실상 전체다. */
+const MAX_TYPES = 12
+
+export interface SplitShape {
+  eventTypes: string[]
+  /**
+   * 공정 단계 하나로 좁힌 경우 — 그 값을 갈래마다 함께 건다.
+   *
+   * 이 필터를 만나면 갈래를 포기하던 것을 고쳤다(2026-08-29). 원장은 종류를 담아 묻고 그 위에 단계
+   * 칩을 겹치는데, 칩을 고른 순간 예전 경로로 떨어져 **고르지 않은 쪽이 더 빨랐다.**
+   *
+   * 단계 컬럼에는 색인이 없다. 그래도 느려지지 않는다 — 종류 정확일치가 색인으로 시각 순서까지 주고,
+   * 단계는 그 안에서 행마다 확인하는 조건이다(걷는 행이 그 종류의 것으로 이미 좁혀져 있다).
+   */
+  bizStep?: string
+  untilTime?: Date
+  fromTime?: Date
+}
+
+/**
+ * 이 물음이 「여러 종류를 시각순으로」인가 — 아니면 `null`.
+ *
+ * 받는 모양
+ *   `eventType` 을 `in` 으로 · 시각 상한이나 구간 · 시각 내림차순 정렬
+ *
+ * 보내는 모양(일반 경로로)
+ *   자유 검색어 · 그 밖의 필터(축·상관 식별자·업무 단계) · 그 밖의 정렬이나 연산자
+ */
+export function splitShape(params: any, sortings: any[]): SplitShape | null {
+  const filters: any[] = Array.isArray(params?.filters) ? params.filters : []
+  if (typeof params?.search === 'string' && params.search.trim()) return null
+  if (sortings.length !== 1 || sortings[0]?.name !== 'eventTime' || sortings[0]?.desc !== true) return null
+
+  let eventTypes: string[] | undefined
+  let untilTime: Date | undefined
+  let fromTime: Date | undefined
+  let bizStep: string | undefined
+  for (const f of filters) {
+    if (f?.name === 'eventType') {
+      if (f.operator !== 'in' || !Array.isArray(f.value)) return null
+      const types: string[] = f.value.map((v: unknown) => String(v ?? '').trim()).filter((t: string) => !!t)
+      /* 하나면 나눌 것이 없다(이미 정확일치라 색인을 탄다). 너무 많으면 사실상 전체다. */
+      if (types.length < 2 || types.length > MAX_TYPES) return null
+      if (eventTypes) return null
+      eventTypes = [...new Set(types)]
+    } else if (f?.name === 'bizStep') {
+      /* 하나로 좁힌 경우만 받는다 — 여러 값이면 종류 × 단계로 갈래가 곱해진다. */
+      if (f.operator !== 'eq') return null
+      const v = String(f.value ?? '').trim()
+      if (!v) return null
+      if (bizStep) return null
+      bizStep = v
+    } else if (f?.name === 'eventTime') {
+      if (f.operator === 'lte' || f.operator === 'lt') {
+        untilTime = absoluteTime(f.value) ?? undefined
+        if (!untilTime) return null
+      } else if (f.operator === 'between' && Array.isArray(f.value)) {
+        fromTime = absoluteTime(f.value[0]) ?? undefined
+        untilTime = absoluteTime(f.value[1]) ?? undefined
+        if (!fromTime || !untilTime) return null
+      } else return null
+    } else return null
+  }
+  return eventTypes ? { eventTypes, untilTime, fromTime, bizStep } : null
+}
+
+/**
+ * **나눠 물은 갈래들을 합쳐 앞에서 `limit` 개** — 이 규율이 정확성의 근거다.
+ *
+ * ── 왜 갈래마다 `limit` 까지 받아야 하나 ────────────────────────────────────
+ * 갈래마다 `limit` 개를 받아 합치면, 합친 것의 앞 `limit` 개는 **전체에서도** 앞 `limit` 개다.
+ * 어떤 갈래에서 빠진 행은 그 갈래의 `limit` 번째보다 뒤이고, 우리는 전체에서 `limit` 개만 취하므로
+ * 그 행이 이 페이지에 들어올 수 없다.
+ *
+ * 갈래마다 **더 적게** 받으면 그 성질이 깨진다. 한 갈래가 앞을 다 차지하는 경우
+ * (종류 A 의 마지막이 종류 B 의 첫째보다 앞선다) 그 갈래에서 못 받은 것이 빠지고, 결과는 구간의
+ * 앞부분만 계산한 것이 된다 — 그런데 화면은 「일부만 읽었다」고만 말하고 어느 부분인지는 말하지 못한다.
+ * (2026-08-28 · UX 레인이 미리 짚어 준 함정이다.)
+ *
+ * 그래서 이 함수는 **`limit` 미만으로 받은 갈래가 있으면 그것을 말한다** — 부르는 쪽이 그 상태로
+ * 답하지 않게.
+ */
+export function mergeStreams<T>(
+  streams: readonly T[][],
+  limit: number,
+  /** 앞에 와야 하는 것이 음수 — `Array.prototype.sort` 와 같은 규약. */
+  compare: (a: T, b: T) => number
+): { items: T[]; capped: boolean; underfilled: boolean } {
+  const underfilled = streams.some(s => s.length > limit)
+  const merged = streams.flat().sort(compare)
+  return {
+    items: merged.slice(0, limit),
+    /* 합친 것이 상한을 넘었으면 더 있었다는 뜻이다 — 잘랐다는 사실을 부르는 쪽이 말해야 한다. */
+    capped: merged.length > limit || streams.some(s => s.length >= limit),
+    /* 갈래가 상한보다 많이 받아 왔다 — 있을 수 없는 일이므로 부르는 쪽이 알아야 한다. */
+    underfilled
+  }
+}

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

@@ -0,0 +1,144 @@
+import { getRepository } from '@things-factory/shell'
+
+import { TwinEvent } from '../twin-event/twin-event.js'
+import { absoluteTime } from '../../engine/read-time.js'
+import { MAX_SPLIT, type SplitShape } from './event-type-split-shape.js'
+
+/*
+ * **여러 종류를 시각순으로 — 종류를 하나씩 나눠 묻는다** (2026-08-28 실측).
+ *
+ * ── 무엇이 느렸나 ───────────────────────────────────────────────────────────
+ * 에너지 원장은 「이 여덟 종류를 시각 내림차순으로 50건」을 묻는다. 그 모양에서 sqlite 는 종류 색인을
+ * **버린다**:
+ *
+ *   종류 IN + 시각순     SEARCH USING INDEX ix_twin_event_1 (domain, instance)   37.181초 · 결과 0건
+ *   같은 조건 · 정렬 없음  SEARCH USING INDEX ix_twin_event_7 (…, event_type=?)     0.003초
+ *   종류 하나 + 시각순    SEARCH USING INDEX ix_twin_event_7 (…, event_type=?)     0.003초
+ *
+ * 정렬을 붙이는 순간 여러 종류의 순서를 합칠 방법이 없어, 시각 색인으로 337만 행을 걸으며 행마다
+ * 종류를 확인한다. 승화푸드에 에너지 사건은 0건이다 — **없는 것을 찾느라 37초**를 쓴다.
+ *
+ * 360 이력이 64초였던 것과 같은 부류다: **거르는 축과 정렬 축이 어긋난다.**
+ *
+ * ── 고침 ────────────────────────────────────────────────────────────────────
+ * 종류를 **정확일치로 하나씩** 물으면 색인이 시각 순서까지 그대로 준다(정렬이 사라진다). 여덟 종류면
+ * 질의 여덟 개이고 각 0.003초다. 받은 것을 시각순으로 합쳐 한 페이지를 만든다.
+ *
+ * 새 색인도, 새 테이블도 필요 없다 — 있는 색인을 쓰게 하는 것이 전부다.
+ *
+ * ── 좁게 잡는다 ─────────────────────────────────────────────────────────────
+ * 이 모양이 아닌 물음은 답하지 않고(`null`) 저널의 일반 경로로 보낸다. 억지로 답하면 목록이 알리지
+ * 않고 달라진다.
+ *
+ * ── ★ **이 갈래를 걷을 조건** ────────────────────────────────────────────────
+ * 앱에서 종류를 여러 값으로 보내는 곳은 **에너지 원장 한 곳뿐**이다(2026-08-28 확인). 그 화면이
+ * 종류를 하나씩 고르는 모양으로 바뀌면 이 갈래를 부르는 데가 없어진다 — 그때 **지운다.**
+ *
+ * 부르는 데가 없는 갈래를 들고 있으면, 그것이 무언가를 받쳐 주는 것처럼 보이면서 실제로는 아무것도
+ * 하지 않는다. 지금 살려 두는 이유는 하나다: 실 고객 트윈에서 37초 질의가 돌고 있고 화면 수정은
+ * 다른 레인의 일이다.
+ */
+
+export interface SplitPage {
+  items: TwinEvent[]
+  nextCursor?: string
+}
+
+/**
+ * 나눠 묻고 합쳐 한 페이지 — 답할 수 없으면 `null`.
+ *
+ * 이어 읽기 지점은 **모든 갈래에 같이** 건다. 그래야 합친 결과가 커서 아래에서만 나온다 — 갈래마다
+ * 다르게 걸면 어떤 종류는 이미 지나간 구간을 다시 낸다.
+ */
+export async function eventTypeSplitPage(
+  domainId: string,
+  instanceIds: string[],
+  shape: SplitShape,
+  limit: number,
+  /** 동시각을 가리는 축 — 트윈 하나면 `revision`, 여럿이면 기본키(§`cursorTiebreak`). */
+  tiebreak: 'revision' | 'id',
+  after?: string
+): Promise<SplitPage | null> {
+  const pairs = instanceIds.length * shape.eventTypes.length
+  if (!pairs || pairs > MAX_SPLIT) return null
+
+  let cursor: { at: Date; tie: string | number } | null = null
+  if (after) {
+    cursor = decodeCursorPair(after)
+    if (!cursor) return null
+  }
+
+  const rows: TwinEvent[][] = []
+  for (const instanceId of instanceIds) {
+    for (const eventType of shape.eventTypes) {
+      const qb = getRepository(TwinEvent)
+        .createQueryBuilder('e')
+        .where('e.domain = :domainId', { domainId })
+        .andWhere('e.instanceId = :instanceId', { instanceId })
+        /* **정확일치**가 요점이다 — 그래야 색인이 시각 순서까지 준다(§ 위 실측). */
+        .andWhere('e.eventType = :eventType', { eventType })
+      /* 단계는 색인이 아니라 행 조건이다 — 종류 정확일치가 이미 걷는 범위를 좁혀 놓았다. */
+      if (shape.bizStep) qb.andWhere('e.bizStep = :bizStep', { bizStep: shape.bizStep })
+      if (shape.fromTime) qb.andWhere('e.eventTime >= :fromTime', { fromTime: shape.fromTime })
+      if (shape.untilTime) qb.andWhere('e.eventTime <= :untilTime', { untilTime: shape.untilTime })
+      if (cursor) {
+        qb.andWhere(`(e.eventTime < :curAt OR (e.eventTime = :curAt AND e.${tiebreak} < :curTie))`, {
+          curAt: cursor.at,
+          curTie: cursor.tie
+        })
+      }
+      const page = await qb
+        .orderBy('e.eventTime', 'DESC')
+        .addOrderBy(`e.${tiebreak}`, 'DESC')
+        .limit(limit)
+        .getMany()
+        .catch(() => null)
+      /* 한 갈래라도 못 읽으면 합친 결과가 반쪽이다 — 반쪽을 전부인 것처럼 내지 않는다. */
+      if (!page) return null
+      rows.push(page)
+    }
+  }
+
+  /*
+   * 합친다. 갈래마다 `limit` 까지 받았으므로, 합쳐서 앞의 `limit` 개는 **전체에서도** 앞의 `limit` 개다
+   * (각 갈래가 자기 안에서 정렬돼 있고 그보다 앞선 것을 빠뜨릴 수 없다).
+   */
+  const merged = rows
+    .flat()
+    .sort((a: any, b: any) => {
+      /* `getMany` 는 엔티티를 주므로 시각이 이미 날짜다 — 감싸면 드라이버 값을 손으로 읽는 모양이 된다. */
+      const at = (b.eventTime as Date).getTime() - (a.eventTime as Date).getTime()
+      if (at !== 0) return at
+      const x = a[tiebreak]
+      const y = b[tiebreak]
+      return x === y ? 0 : x < y ? 1 : -1
+    })
+    .slice(0, limit)
+
+  const last: any = merged[merged.length - 1]
+  const nextCursor =
+    merged.length === limit && last?.eventTime instanceof Date && last[tiebreak] !== undefined
+      ? encodeCursorPair(last.eventTime, last[tiebreak])
+      : undefined
+
+  return { items: merged, nextCursor }
+}
+
+/** 저널 경로와 같은 커서 — `[eventTime, 동시각 축]`(§`buildNextCursor`). */
+function encodeCursorPair(at: Date, tie: string | number): string {
+  return Buffer.from(JSON.stringify([at, tie]), 'utf8').toString('base64url')
+}
+
+function decodeCursorPair(cursor: string): { at: Date; tie: string | number } | null {
+  let values: unknown
+  try {
+    values = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'))
+  } catch {
+    return null
+  }
+  if (!Array.isArray(values) || values.length !== 2) return null
+  const at = absoluteTime(values[0])
+  const tie = values[1]
+  if (!at || (typeof tie !== 'string' && typeof tie !== 'number')) return null
+  return { at, tie }
+}

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

@@ -0,0 +1,20 @@
+/**
+ * 지난 기록 조회의 정렬 축 — **부르는 쪽이 무엇으로 물었는지에 맞춘다.**
+ *
+ * 리졸버 안에 두면 이 규칙을 확인할 방법이 소스를 글자로 전수 조회하는 것뿐이다. 규칙 자체를 부를 수 있게
+ * 밖으로 뺀다(`test/journal-order-axis.test.ts`).
+ */
+export function journalOrder(q: {
+  untilTime?: string | null
+  fromTime?: string | null
+  fromRevision?: number | null
+  toRevision?: number | null
+}): {
+  eventTime?: 'DESC'
+  revision: 'DESC'
+} {
+  /* `revision` 으로 물었으면 그 순서가 물음의 답이다. 거르는 축과 정렬 축을 맞추는 규칙과도 같다. */
+  const byTime = q.untilTime != null || q.fromTime != null
+  if (!byTime && (q.fromRevision != null || q.toRevision != null)) return { revision: 'DESC' }
+  return { eventTime: 'DESC', revision: 'DESC' }
+}