@things-factory/headless-twin 10.0.15 → 10.0.18

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

@@ -0,0 +1,3 @@
+import { TwinBackfillResolver } from './twin-backfill-resolver.js'
+
+export const resolvers = [TwinBackfillResolver]

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

@@ -0,0 +1,35 @@
+import { Arg, Ctx, Directive, Mutation, Resolver } from 'type-graphql'
+import { ScalarObject } from '@things-factory/shell'
+
+import { backfillPeriodFacts } from './backfill-period-facts.js'
+
+/*
+ * 지난 기록 채우기의 **문** — 커넥터가 트윈이 없던 동안의 날들을 뒤늦게 넣는다.
+ *
+ * ── 왜 문을 따로 두나 (2026-08-30) ────────────────────────────────────────
+ * 라이브 유입과 판단이 다르다. 라이브는 트윈의 「지금」을 바꾸고, 이쪽은 저널에만 쓴다. 같은 문으로
+ * 받으면 옛 표본이 가드에 막히거나 트윈의 시계가 과거로 끌린다(§`backfill-period-facts`).
+ *
+ * 레코드의 **모양은 라이브와 같다** — 커넥터가 다른 어휘를 배울 필요가 없다. 다른 것은 받는 종류뿐이고,
+ * 그 판단은 커널의 유입과 `judgeBackfill` 이 한다.
+ *
+ * ── 왜 이 파일이 늦게 생겼나 ──────────────────────────────────────────────
+ * 채우기 자체는 만들어 두고 **부르는 곳을 만들지 않아** 쓸 수 없는 채로 있었다. 8월 29일 발전량을
+ * 되살리려다 드러났다. 같은 부류를 그날 두 번 겪었다(커널의 발전 기간 문도 없었다).
+ */
+@Resolver()
+export class TwinBackfillResolver {
+  /* 트윈의 모든 변경과 같은 게이트다(ADR-0027) — 저널에 사실을 적는 일이므로 변경이다. */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Mutation(returns => ScalarObject, {
+    description:
+      'Backfill closed-period facts into a twin journal without touching its live state. Records use the same shape as live ingest; only closed-period facts are accepted (usage/generation periods, generation price, tariff basis, bill). Point-in-time observations are refused with a reason, as are times beyond journal retention. Re-running is safe: a period already present is skipped, because a closed period is identified by its content. Returns { written, skipped, refused }.'
+  })
+  async backfillTwinPeriodFacts(
+    @Arg('instanceId') instanceId: string,
+    @Arg('records', type => [ScalarObject]) records: unknown[],
+    @Ctx() context: ResolverContext
+  ): Promise<{ written: number; skipped: number; refused: { record: unknown; reason: string }[] }> {
+    return await backfillPeriodFacts({ domainId: context.state.domain.id, instanceId, records })
+  }
+}

package/server/service/twin-control/twin-control-mutation.ts

@@ -1,7 +1,7 @@
 import { twinError } from '../../engine/log.js'
 import { Arg, Ctx, Mutation, Query, Resolver, Directive } from 'type-graphql'
 
-import { validateScenario } from '@operato/twin-kernel'
+import { validateScenario } from '@operato/ops-contract'
 
 import { ScalarObject } from '@things-factory/shell'
 
@@ -50,7 +50,7 @@ export class TwinControlMutation {
      * 증명할 수 있다. 커널이 거절한 것도 남긴다 — 무엇을 시도했는지가 감사의 절반이다.
      *
      * 기록이 실패해도 커맨드 결과는 그대로 돌려준다. 감사가 본업을 막으면 안 되지만, 실패를 삼키지도
-     * 않는다(로그에 남긴다) — 조용히 안 남으면 나중에 "기록이 없다" 와 "일이 없었다" 를 구분 못 한다.
+     * 않는다(로그에 남긴다) — 알리지 않고 안 남으면 나중에 "기록이 없다" 와 "일이 없었다" 를 구분 못 한다.
      */
     try {
       const audit = buildCommandAudit({ command: cmdWithOrigin, ack, actor: context.state.user, at: new Date() })

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

@@ -29,7 +29,7 @@ export interface TwinEventKeys {
 
 /*
  * 컬럼 길이 상한. GS1 식별자(EPC URN·GDTI·SGLN)는 규격상 이보다 훨씬 짧다.
- * 넘치는 값이 오면 **조용히 자르지 않고** 경고를 남긴다 — 색인이 원본과 다르면 검색 결과가 거짓이 되는데,
+ * 넘치는 값이 오면 **알리지 않고 자르지 않고** 경고를 남긴다 — 색인이 원본과 다르면 검색 결과가 거짓이 되는데,
  * 그 사실이 어디에도 안 남으면 아무도 모른다.
  */
 const MAX_KEY = 255
@@ -128,7 +128,7 @@ export function equipmentIdOf(envelope: any): string | undefined {
  * EPCIS 행위 — `ADD`·`OBSERVE`·`DELETE`. 세 값이 아니면 `undefined`(원천의 잡값을 색인에 넣지 않는다).
  *
  * 이 키는 검색 축이 아니라 **판별식**이다: 되풀어 읽는 스냅샷은 원리적으로 `DELETE` 를 못 낸다.
- * 그래서 「이 트윈이 반출을 한 번이라도 접었는가」가 진짜 delta 피드의 증거인데, payload 안에 있는
+ * 그래서 「이 트윈이 반출을 한 번이라도 계산했는가」가 진짜 delta 피드의 증거인데, payload 안에 있는
  * 동안에는 5개 드라이버 어디에서도 그 질문을 할 수 없었다. 운영 델타에는 행위가 없다 — 비운다.
  */
 export function actionOf(envelope: any): string | undefined {

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

@@ -6,7 +6,7 @@ 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.' })
@@ -48,4 +48,21 @@ export class TwinEventList {
    */
   @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
+
+  /*
+   * **앞부분이 지워졌다** — 보관 기간 정리가 이 트윈의 오래된 사건을 지운 경우 (2026-08-27).
+   *
+   * 정리는 선언된 보관 기간(기본 7일)보다 오래된 사건을 지운다. 그러면 이 목록의 첫 페이지 뒤로 더
+   * 내려가도 어느 지점에서 기록이 끝난다. 화면이 그것을 말하지 않으면 사람은 「이 트윈은 그때부터
+   * 시작했다」로 읽는다. 없었던 것과 지워진 것은 다른 사실이다.
+   *
+   * 값은 저장하지 않고 조회할 때 구한다(남아 있는 가장 작은 리비전). 저장하면 실제 데이터와 어긋날 수
+   * 있고, 어긋나면 어느 쪽이 사실인지 알 수 없다.
+   */
+  @Field(type => Int, {
+    nullable: true,
+    description:
+      'The oldest revision still stored for this twin. When it is greater than 1, older events were deleted by the journal retention policy: the screen must say the record starts here rather than implying the twin began at this point. NULL when the caller asked for more than one twin (the axis is per twin) or when nothing is stored.'
+  })
+  oldestRevision?: number
 }

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

@@ -34,8 +34,34 @@ import { Domain, ScalarObject } from '@things-factory/shell'
 @Index('ix_twin_event_4', (e: TwinEvent) => [e.domain, e.instanceId, e.orderId], { unique: false })
 /* ix_5 — "이 지시가 무엇을 일으켰나". 감사 기록의 commandId 로 저널을 다시 계산하는 축. */
 @Index('ix_twin_event_5', (e: TwinEvent) => [e.domain, e.correlationId], { unique: false })
-/* ix_6 — "반출을 한 번이라도 접었나". 없으면 그 질문이 인스턴스 저널 전량 주사가 된다. */
+/* ix_6 — "반출을 한 번이라도 계산했나". 없으면 그 질문이 인스턴스 저널 전량 주사가 된다. */
 @Index('ix_twin_event_6', (e: TwinEvent) => [e.domain, e.instanceId, e.action], { unique: false })
+/*
+ * ix_7 — **"이 종류의 사실을 시각순으로"** (2026-08-25 실측으로 추가)
+ *
+ * 이 축이 없어서 공정 타임라인이 22초였다. 종류로 거르고 시각으로 정렬하는 조회가 갈 곳이 없었다:
+ *
+ *   ix_2 (…, eventType, revision)   종류는 걸러지고 정렬이 **적힌 순서**다 → 4월 사실을 최근으로 그렸다
+ *   ix_1 (…, eventTime)             정렬은 맞고 **종류를 못 거른다** → 행마다 테이블을 열어 확인한다
+ *
+ * 뒤쪽으로 걸으면 그 트윈에서 찾는 종류가 멈춘 시점까지의 모든 행을 읽고 버린다. 승화푸드에서 작업
+ * 사실은 8월 22일에 멈춰 있고 그 뒤로 리비전이 110만 늘었으므로, 200건에 닿기까지 110만 행을 열었다.
+ *
+ * 위 주석이 「측정을 근거로 추가할 일이지 지레 얹을 일은 아니다」라고 적어 두었다. 그 측정이 나왔다.
+ */
+@Index('ix_twin_event_7', (e: TwinEvent) => [e.domain, e.instanceId, e.eventType, e.eventTime], { unique: false })
+/*
+ * ix_8 — **"이 트윈의 오래된 기록"** (2026-08-27 실측으로 추가)
+ *
+ * 보관 기간 정리가 `created_at` 으로 자르는데(보관은 저장 나이의 문제다) 그 축에 인덱스가 없었다.
+ * 그래서 정리가 매 배치마다 그 트윈의 저널을 전량 주사했다.
+ *
+ *   hatio-mx2 의 7일 밖 행을 세기      208초   ← 1,029만 행을 전부 읽는다(7일 밖은 2,446건뿐이다)
+ *   revision 으로 한 행 짚기           0.004초
+ *
+ * 정리는 한 창에 2초만 쓰도록 예산이 걸려 있어서, 그 2초를 주사에 다 쓰고 44건만 지우고 멈췄다.
+ */
+@Index('ix_twin_event_8', (e: TwinEvent) => [e.domain, e.instanceId, e.createdAt], { unique: false })
 @ObjectType({ description: 'Append-only twin event journal record (EPCIS event or operational delta).' })
 export class TwinEvent {
   @PrimaryGeneratedColumn('uuid')
@@ -71,8 +97,8 @@ export class TwinEvent {
    * 이 사실이 **어느 공장에서** 일어났나 — `TwinStructure.rev`.
    *
    * 이것이 없던 시절에는 구조가 바뀌면 저널을 통째로 지우는 것이 유일한 길이었다(안 지우면 옛
-   * 이벤트를 새 공장에 대고 접어 이력이 거짓말을 한다). 이 한 칸이 셋째 길을 연다 — 재생이
-   * 구조가 바뀌는 지점에서 전환한 뒤 이어 접는다.
+   * 이벤트를 새 공장에 대고 계산해 이력이 거짓말을 한다). 이 한 칸이 셋째 길을 연다 — 재생이
+   * 구조가 바뀌는 지점에서 전환한 뒤 이어서 계산한다.
    *
    * **비어 있을 수 있다**: 컬럼이 생기기 전에 쓰인 행이다. 그 행들은 **가장 오래된 리비전**에
    * 속한다(0 을 채워 넣지 않는다 — 0 은 "모름" 이 아니라 유효한 번호처럼 보인다).
@@ -85,7 +111,7 @@ export class TwinEvent {
    * 이 사실이 일어난 시각(트윈의 시계). **날짜 타입이다.**
    *
    * 예전에는 문자열이었다. 읽을 때마다 `Date.parse` 했고, 정렬은 UTC ISO 만 들어온다는 전제 위에서
-   * 사전식 비교가 우연히 맞았다 — `+09:00` 오프셋 표기가 하나 섞이면 조용히 순서가 틀린다.
+   * 사전식 비교가 우연히 맞았다 — `+09:00` 오프셋 표기가 하나 섞이면 알리지 않고 순서가 틀린다.
    * 그 전제는 컬럼 어디에도 적혀 있지 않았다.
    *
    * **타입 이름을 적지 않는다** (2026-08-19 Postgres 부팅 실패로 고침).
@@ -108,11 +134,11 @@ export class TwinEvent {
    * payload 가 여전히 정본이고 이것들은 **파생 색인**이다 — 새로운 진실이 아니라 찾을 수 있게 하는 장치.
    * simple-json(TEXT) 안의 값은 5개 DB 드라이버 공통으로 거를 방법이 없어서(멀티DB 호환 규칙상
    * DB별 JSON 연산자 금지) 승격 외의 선택지가 없다.
-   * 길이 상한 255 는 GS1 식별자 규격 대비 충분하며, 넘치는 값은 조용히 잘리지 않고 경고를 남긴다.
+   * 길이 상한 255 는 GS1 식별자 규격 대비 충분하며, 넘치는 값은 알리지 않고 잘리지 않고 경고를 남긴다.
    *
    * ── 축을 새로 추가할 때 ──────────────────────────────────────────────────
    * 새 승격 컬럼을 만들면 **이미 쌓인 행은 비어 있다.** 그 행들은 새 축으로 검색되지 않고,
-   * 사용자에게는 "과거가 없는 것" 으로 보인다(조용히 빠진 데이터).
+   * 사용자에게는 "과거가 없는 것" 으로 보인다(알리지 않고 빠진 데이터).
    *
    * 예전에는 기동 훅이 매번 테이블을 살펴 채웠다. 그건 두 가지로 틀렸다 — 저널이 커질수록 부팅이
    * 느려지고, "bizStep 이 비었으면 옛 행" 이라는 전제를 코드에 고정해 그 전제가 깨지는 순간

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

@@ -3,7 +3,7 @@
  *
  * ── 왜 순수 모듈인가 (2026-08-15) ───────────────────────────────────────────
  * 이 표가 리졸버 안에 있어서 시험이 불러올 수 없었다(type-graphql·shell 을 물고 있다). 그런데 여기서
- * 틀리면 예측 그래프 전체가 조용히 다른 것을 그린다 — 오류 없이. 규칙은 시험이 닿는 자리에 둔다.
+ * 틀리면 예측 그래프 전체가 알리지 않고 다른 것을 그린다 — 오류 없이. 규칙은 시험이 닿는 자리에 둔다.
  *
  * ── 에너지 지표를 더한 이유 ─────────────────────────────────────────────────
  * 예측 화면의 지표가 물류 여섯(재고·점유·작업·오더·출고·백로그)으로 고정돼 있어서, 에너지 트윈을

package/server/service/twin-forecast/gap-analytics.ts

@@ -23,7 +23,7 @@ export interface GapPoint {
   modelAbsError: number
 }
 
-/** 합산 결과 + **무엇을 못 넣었는지.** 조용히 줄이지 않는다. */
+/** 합산 결과 + **무엇을 못 넣었는지.** 알리지 않고 줄이지 않는다. */
 export interface AggregateResult {
   points: GapPoint[]
   /** 한 트윈이라도 재지 못해 통째로 뺀 vantage 수. */

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