@things-factory/headless-twin 10.0.14 → 10.0.17

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

@@ -1,4 +1,5 @@
 import { twinLog } from '../../engine/log.js'
+import { hydratedDate } from '../../engine/read-time.js'
 import { Arg, Ctx, Int, Mutation, Query, Resolver, Directive} from 'type-graphql'
 
 import { getRepository, ScalarObject } from '@things-factory/shell'
@@ -80,13 +81,31 @@ const calKey = (d: string, i: string, m: string, h: number) => `${d}:${i}:${m}:$
  * 지평 H 만큼 앞을 봐야 "그때 예측한 것"과 "실제로 벌어진 것"을 맞대 볼 수 있으므로 끝에서 H 를 뺀다.
  */
 async function gapWindow(domainId: string, instanceId: string, H: number): Promise<{ t0: number; lastVantage: number } | null> {
-  const where = { domain: { id: domainId }, instanceId }
+  /*
+   * ── **양 끝을 집계로 묻는다** (2026-08-28) ──────────────────────────────────
+   *
+   * 예전에는 `findOne({ where: { domain: { id } }, order: { eventTime } })` 두 번이었다. 관계를 가진
+   * 엔티티에서 `findOne` 은 두 단계 질의가 되고 **안쪽에 상한이 없다** — 그 트윈의 저널을 전부 만든 뒤
+   * 한 줄을 고른다. 승화푸드는 337만 행이고, 그것을 두 번 했다.
+   *
+   * `MIN`/`MAX` 는 `(domain, instance, event_time)` 색인의 양 끝을 집으므로 각각 한 줄이다.
+   * 이 파일의 다른 자리와 같은 규율이다(§`twin-engine` 의 `tipOf`).
+   */
   const repo = getRepository(TwinEvent)
-  const first = await repo.findOne({ where, order: { eventTime: 'ASC' } })
-  const last = await repo.findOne({ where, order: { eventTime: 'DESC' } })
-  if (!first?.eventTime || !last?.eventTime) return null
-  const t0 = first.eventTime.getTime()
-  const lastVantage = last.eventTime.getTime() - H
+  const edge = (agg: 'MIN' | 'MAX') =>
+    repo
+      .createQueryBuilder('e')
+      .select(`${agg}(e.eventTime)`, 'at')
+      .where('e.domain = :domainId', { domainId })
+      .andWhere('e.instanceId = :instanceId', { instanceId })
+      .getRawOne<{ at: unknown }>()
+  const [firstRow, lastRow] = await Promise.all([edge('MIN'), edge('MAX')])
+  /* 드라이버가 준 값은 시간대가 없을 수 있다 — 컬럼 변환을 지나게 한다(§`hydratedDate`). */
+  const first = hydratedDate(repo, 'eventTime', firstRow?.at)
+  const last = hydratedDate(repo, 'eventTime', lastRow?.at)
+  if (!first || !last) return null
+  const t0 = first.getTime()
+  const lastVantage = last.getTime() - H
   return lastVantage > t0 ? { t0, lastVantage } : null
 }
 
@@ -188,7 +207,7 @@ export class TwinForecastQuery {
      * **배운 모델에만 적용한다.** 보정은 "그때 모델이 이만큼 치우쳐 있다" 를 배운 것이다. 소요시간
      * 추정기(실측·거리)나 공정 명세가 바뀌어 모델이 달라지면 그 편향은 더 이상 사실이 아니고, 그대로
      * 밀어 주면 이중 보정이 된다. 그래서 지문을 비교하고, 다르면 적용하지 않되 **그 사실을 응답에
-     * 싣는다** — 조용히 사라지면 사용자는 학습이 왜 안 듣는지 알 수 없다(다시 배우면 된다).
+     * 싣는다** — 오류 없이 사라지면 사용자는 학습이 왜 안 듣는지 알 수 없다(다시 배우면 된다).
      * 지문을 알 수 없을 때는 비교하지 않는다(모르는 것을 근거로 보정을 끊지 않는다).
      */
     const basis = await TwinEngine.modelBasis(domainId, instanceId)
@@ -312,7 +331,7 @@ export class TwinForecastQuery {
       /*
        * **가정이 어떻게 됐나** — 걸린 개입·거절된 개입·덮어쓴 선언.
        *
-       * 이것을 감추면 두 가지가 조용해진다: 걸리지 않은 가정(「걸었는데 왜 안 바뀌나」)과, 덮어쓴
+       * 이것을 감추면 두 가지가 들어온 것이 없어진다: 걸리지 않은 가정(「걸었는데 왜 안 바뀌나」)과, 덮어쓴
        * 선언(사용자가 what-if 결과를 트윈의 현재 상태로 읽는다). 실제로 실행한 fork(`fc`)에서 읽는다 —
        * 가정을 겪은 것은 그쪽이다.
        */
@@ -342,10 +361,10 @@ export class TwinForecastQuery {
        *
        * 그런데 그 카운터는 **fork 안에** 있고 fork 는 버려진다. 여기서 싣지 않으면 아무에게도 닿지
        * 않는다 — 리듀서가 오래 세어 온 값을 스냅샷이 떨어뜨려 그것을 읽도록 쓰인 검사가 영원히
-       * 조용했던 것과 **같은 실수**다. 세어 놓고 내보내지 않으면 안 센 것과 같다.
+       * 아무 신호도 내지 않았던 것과 **같은 실수**다. 세어 놓고 내보내지 않으면 안 센 것과 같다.
        *
        * 왜 화면이 이것을 알아야 하나: 계보는 **회수 범위**를 정하는 사슬이다. 구멍이 있는데 온전한
-       * 것처럼 보이면 회수가 조용히 좁아진다. 식품에서 그것은 되돌릴 수 없다.
+       * 것처럼 보이면 회수가 알리지 않고 좁아진다. 식품에서 그것은 되돌릴 수 없다.
        *
        * 두 곳에서 읽어 **큰 값**을 낸다 — 분포(회차 R개의 최대)와 궤적 fork 는 **둘 다 실제로 실행됐다**.
        * 한쪽만 보면 다른 쪽이 겪은 구멍을 잃는다.
@@ -394,7 +413,7 @@ export class TwinForecastQuery {
      * 시각이 되어, 합산이 다른 시점의 값을 더한다(`aggregatePoints` 주석 참조).
      *
      * 저널이 없거나 지평 H 를 담을 만큼 길지 않은 트윈은 **백테스트에 참여할 수 없다.** 그런 트윈은
-     * 빼되 누구를 뺐는지 돌려준다 — 조용히 빼면 화면은 그 트윈까지 포함한 공장 총량으로 읽는다.
+     * 빼되 누구를 뺐는지 돌려준다 — 알리지 않고 빼면 화면은 그 트윈까지 포함한 공장 총량으로 읽는다.
      */
     const windows = await Promise.all(ids.map(async id => ({ id, w: await gapWindow(domainId, id, H) })))
     const usable = windows.filter(x => x.w)

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

@@ -29,7 +29,7 @@ import { TwinIngestWindow } from './twin-ingest-window.js'
  * 한 번에 돌려주는 창 수 상한 — 144창 × 10분 = 24시간.
  *
  * 상한이 필요한 이유는 이 표가 **자란다**는 것이다(트윈 1,000개에 하루 14.4만 행). 상한에서 밀려난
- * 수는 **세어서 낸다** — 조용히 자르면 화면이 「그 앞에는 아무 일도 없었다」로 읽는다.
+ * 수는 **세어서 낸다** — 알리지 않고 자르면 화면이 「그 앞에는 아무 일도 없었다」로 읽는다.
  */
 export const HISTORY_WINDOW_LIMIT = 144
 

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

@@ -11,7 +11,7 @@ import { TwinIngestWindow } from './twin-ingest-window.js'
  * 두었고(`onIngestWindowClosed`), 이 파일이 부팅에서 한 번 등록한다. 그래서 기록 경로가 갈리지 않는다.
  *
  * ── 실패를 삼키지 않는다 ────────────────────────────────────────────────────
- * 쓰기가 터져도 메모리 장부는 계속 굴러간다(`rollIngestWindow` 가 훅을 감싼다). 다만 **조용히 넘기지는
+ * 쓰기가 터져도 메모리 장부는 계속 굴러간다(`rollIngestWindow` 가 훅을 감싼다). 다만 **알리지 않고 넘기지는
  * 않는다** — 실패를 로그로 남긴다. 그러지 않으면 추이 표에 구멍이 생긴 이유를 나중에 알 수 없다.
  *
  * ── 왜 await 하지 않나 ──────────────────────────────────────────────────────

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' }
+}