@things-factory/headless-twin 10.0.14 → 10.0.17

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

@@ -0,0 +1,196 @@
+import { getRepository } from '@things-factory/shell'
+
+import { twinLog, twinWarn } from '../../engine/log.js'
+import { TwinEvent } from '../twin-event/twin-event.js'
+import { TwinInstance } from '../twin-instance/twin-instance.js'
+import { TwinSubjectEvent } from './twin-subject-event.js'
+import { writeSubjectRows } from './twin-subject-writer.js'
+import { itemResolverFor } from './item-resolver.js'
+
+/*
+ * **이미 저장된 사건을 이 표로 옮긴다** — 요청받은 트윈만.
+ *
+ * ── 왜 기본이 아닌가 ────────────────────────────────────────────────────────
+ * 이 표의 규칙은 「앞으로만 채운다」다. 그래야 새 조회 축이 필요할 때마다 3,128만 줄을 다시 만드는
+ * 구조가 되지 않는다(설계: read-models.md §4).
+ *
+ * 그런데 이미 쌓인 트윈에서 이력을 보려면 그 구간이 있어야 한다. 그래서 **부르면 채우는 도구**로 둔다 —
+ * 마이그레이션이 아니고, 부팅에 자동으로 돌지도 않는다. 트윈을 지정해 부른다.
+ *
+ * ── 어디까지 옮겼는지 적어 둔다 (2026-08-27 · 세 번 틀린 뒤) ─────────────────
+ * 저장하지 않고 표의 내용으로 진행 지점을 알아내려 했고 세 번 틀렸다.
+ *
+ *   ① 표의 최대 리비전 뒤부터    앞으로 채워진 줄의 최댓값이 곧 저널의 끝이라 소급을 다 건너뛴다
+ *   ② 표의 최소 리비전 앞까지    소급이 1부터 적으면 최솟값이 1이 되어 구간이 0으로 접힌다
+ *   ③ 표의 최소 시각 아래로      사건이 시각순으로 오지 않는 트윈에서 곧바로 끝난다
+ *
+ * ③이 결정적이었다. 승화푸드 커넥터는 과거 기록을 되읽으므로 방금 들어온 사건의 시각이 2024년 10월이다.
+ * 그래서 표의 가장 오래된 시각이 이미 저널의 시작과 같아진다.
+ *
+ * 원인은 하나다. **채워진 것은 구간이 아니라 집합이다.** 리비전으로 보든 시각으로 보든 「어디까지」를
+ * 하나의 경계로 말할 수 없다. 그래서 알아내려 하지 않고 **이 프로세스가 든다**(§`inFlight`).
+ *
+ * 리비전 1부터 순서대로 올라간다. 목표는 **채우기를 시작한 순간의 저널 끝**이다 — 그보다 뒤는 앞으로
+ * 채우는 쪽이 이미 적고 있다.
+ *
+ * ── 규율 ────────────────────────────────────────────────────────────────────
+ * **나눠서 옮긴다.** 한 번에 통째로 읽으면 그동안 호스트가 아무 일도 못 한다(sqlite 는 쓰기가 하나다).
+ * 배치 사이에 루프를 비워 준다.
+ *
+ * **같은 시각의 줄을 반쪽만 적지 않는다.** 한 배치의 가장 오래된 시각에 걸친 줄들은 다음 배치로 넘긴다 —
+ * 반쪽만 적으면 그 시각이 「채워진 것」으로 보이면서 일부가 빠진다.
+ *
+ * **몇 줄을 옮겼고 어디까지 왔는지 말한다.** 알리지 않고 절반만 채우면 화면이 「그 앞에는 사건이 없다」고
+ * 말하게 된다.
+ */
+
+/** 한 번에 읽는 저널 행 수 — 저널 정리와 같은 규율. */
+const READ_BATCH = 5_000
+
+export interface BackfillResult {
+  instanceId: string
+  /** 읽은 저널 행 수. */
+  read: number
+  /** 이 표에 적은 줄 수. */
+  written: number
+  /** 여기까지 옮겼다(저널 리비전). */
+  upToRevision: number
+  /** 목표 — 채우기를 시작한 순간의 저널 끝. */
+  targetRevision: number
+  /** 다 옮겼나. */
+  complete: boolean
+  /** 예산을 다 써서 멈췄나. */
+  paused: boolean
+}
+
+/**
+ * 옮기는 중인 트윈의 목표와 지점 — **이 프로세스 안에서만** 든다.
+ *
+ * 테이블에 적지 않는다(사용자 판단, 2026-08-27). 서버가 내려가면 사라지고, 다음에 부르면 처음부터
+ * 다시 읽는다. 그 대가를 아는 채로 두는 것이다.
+ */
+const inFlight = new Map<string, { upToRevision: number; targetRevision: number }>()
+
+/**
+ * 한 트윈의 저장된 사건을 이 표로 옮긴다 — 예산 안에서.
+ *
+ * 되풀어 부르면 이어서 한다. 넘길 인자가 없다 — 진행 지점을 적어 두기 때문이다.
+ */
+export async function backfillSubjects(
+  domainId: string,
+  instanceId: string,
+  opts: { budgetMs?: number } = {}
+): Promise<BackfillResult> {
+  const budgetMs = opts.budgetMs ?? 30_000
+  const startedMs = Date.now()
+
+  const reg = await getRepository(TwinInstance)
+    .findOne({ where: { domain: { id: domainId }, instanceId } })
+    .catch(() => null)
+  if (!reg?.model) {
+    throw new Error(`twin "${instanceId}" is not registered — no model to resolve declared items with`)
+  }
+  const itemOf = itemResolverFor(domainId, instanceId, reg.model)
+  if (!itemOf) {
+    twinWarn(
+      `[twin-subject] "${instanceId}" 선언된 품목이 없어 품목 줄은 만들지 않는다 — 개체·자리·설비 줄만 옮긴다.`
+    )
+  }
+
+  /*
+   * ── 진행 지점을 **판 안에서만** 든다 (2026-08-27 · 사용자 판단) ────────────────
+   *
+   * 처음에는 테이블에 적었다. 사용자 판단으로 없앴다 — 사건이 들어올 때 파생 테이블도 같이 적히므로,
+   * 옛 사건을 옮기는 일은 새 파생 테이블을 만들 때와 계산 규칙을 고쳐 다시 만들 때뿐이다. 그 두 경우가
+   * 흔하지 않다.
+   *
+   * 대가는 이것이다. 옮기는 중에 서버가 내려가면 그 몫을 다시 읽는다. 335만 건이면 20분쯤이다.
+   *
+   * 그래서 **목표와 지점을 이 프로세스가 든다.** 트윈마다 한 줄이고, 서버가 내려가면 사라진다.
+   */
+  const events = getRepository(TwinEvent)
+  const key = `${domainId}:${instanceId}`
+  let held = inFlight.get(key)
+  if (!held) {
+    /*
+     * 목표는 **처음 부를 때의 저널 끝**이다. 매번 다시 재면 그 사이에 새 사건이 들어와 끝나지 않는다.
+     * 그 뒤의 사건은 저널을 쓸 때 파생 테이블에도 같이 적히므로 이 작업의 몫이 아니다.
+     */
+    const tip = await events
+      .createQueryBuilder('e')
+      .select('MAX(e.revision)', 'max')
+      .where('e.domain = :domainId', { domainId })
+      .andWhere('e.instanceId = :instanceId', { instanceId })
+      .getRawOne<{ max: unknown }>()
+    held = { upToRevision: 0, targetRevision: Number(tip?.max ?? 0) }
+    inFlight.set(key, held)
+  }
+
+  let read = 0
+  let written = 0
+  let paused = false
+  let cursor = held.upToRevision
+  const target = held.targetRevision
+
+  for (;;) {
+    if (cursor >= target) break
+    if (Date.now() - startedMs >= budgetMs) {
+      paused = true
+      break
+    }
+    const rows = await events
+      .createQueryBuilder('e')
+      .where('e.domain = :domainId', { domainId })
+      .andWhere('e.instanceId = :instanceId', { instanceId })
+      .andWhere('e.revision > :cursor', { cursor })
+      .andWhere('e.revision <= :target', { target })
+      .orderBy('e.revision', 'ASC')
+      .take(READ_BATCH)
+      .getMany()
+    if (!rows.length) {
+      cursor = target
+      break
+    }
+
+    read += rows.length
+    written += await writeRows(domainId, instanceId, rows, itemOf)
+    cursor = Number(rows[rows.length - 1].revision)
+    /* 진행 지점을 그때그때 든다 — 중간에 멈춰도 다음 호출이 여기서 잇는다(같은 프로세스 안에서). */
+    held.upToRevision = cursor
+    /* 배치 사이에 루프를 비워 준다 — 이 한 줄이 없으면 나눈 뜻이 없다. */
+    await new Promise(resolve => setImmediate(resolve))
+  }
+
+  held.upToRevision = cursor
+  const complete = cursor >= target
+  /* 다 옮겼으면 들고 있을 이유가 없다 — 다시 부르면 목표를 새로 잡는다(그때는 옮길 것이 없다). */
+  if (complete) inFlight.delete(key)
+  twinLog(
+    `[twin-subject] backfill "${instanceId}" — 저널 ${read}행을 읽어 ${written}줄 적었다 · ` +
+      `리비전 ${cursor}/${target}` +
+      `${complete ? ' · 다 옮겼다' : paused ? ' · 예산을 다 써서 멈췄다 — 다시 부르면 이어서 한다' : ''}`
+  )
+
+  return { instanceId, read, written, upToRevision: cursor, targetRevision: target, complete, paused }
+}
+
+/** 저널 행들을 봉투로 되돌려 적는다 — `payload` 가 봉투 전체다. */
+async function writeRows(domainId: string, instanceId: string, rows: TwinEvent[], itemOf?: any): Promise<number> {
+  return await writeSubjectRows(
+    domainId,
+    instanceId,
+    rows.map(r => ({
+      /*
+       * `payload` 가 봉투 전체다(`{ eventId, eventType, eventTime, tenantId, data: {…} }`). 한 겹 더
+       * 감싸면 키가 묻혀 아무것도 찾지 못한다 — 실측으로 825,000행을 읽어 0줄을 적었다.
+       *
+       * 시각과 종류는 승격 컬럼을 믿는다. payload 안의 값과 컬럼이 어긋난 옛 행이 있을 수 있고,
+       * 이 표의 정렬 축은 컬럼이 정본이다.
+       */
+      envelope: { ...((r as any).payload ?? {}), eventType: r.eventType, eventTime: r.eventTime },
+      revision: Number(r.revision),
+      eventId: r.id
+    })),
+    itemOf
+  )
+}

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

@@ -0,0 +1,101 @@
+import { Field, Int, ObjectType } from 'type-graphql'
+import { Column, CreateDateColumn, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId } from 'typeorm'
+import { Domain } from '@things-factory/shell'
+
+/*
+ * **대상별 사건 목록** — 조회용 파생 표. 사실의 원본은 `twin_events` 다.
+ *
+ * ── 왜 만드나 (2026-08-27 실측) ─────────────────────────────────────────────
+ * 360 화면이 「이 대상의 이력」을 묻고, 그 조회가 64초다. 원인은 「무엇으로 걸러 시각순으로 정렬해
+ * 앞에서 30개」라는 모양에 맞는 목차가 없다는 것이다. 그리고 목차를 얹는 방식으로는 풀리지 않는다.
+ *
+ *   정렬이 목차를 무력화한다      여러 값으로 거르면(IN) 합칠 때 다시 정렬해야 한다
+ *   축이 늘 때마다 목차가 늘어난다  360 의 축 넷을 다 빠르게 하면 `twin_events` 목차가 13개가 된다
+ *   소급 채우기가 매번 든다       목차 하나 만드는 데 3분 36초 · 파일 +2.4GB
+ *   품목 축은 그래도 안 풀린다     저장된 식별자에 품목과 로트가 한 문자열로 붙어 있다
+ *
+ * ── 이 표가 무엇을 담나 ─────────────────────────────────────────────────────
+ * 사건 하나가 가리키는 **대상마다 한 줄**이다. 품목 이동 사건이면 품목·로트·자리로 세 줄이다.
+ * 종류(`subjectKind`)를 값으로 밝히므로 읽는 쪽이 사건 종류표를 들고 있지 않아도 된다. 뜻이
+ * 달라지는 키 칸을 쓰지 않는 이유이고, 그 방식이 틀렸다는 뜻은 아니다 — 정의가 함께 있는
+ * 프레임워크에서는 합리적이다. 이 표는 볼 정의가 없다.
+ *
+ * ── 규칙 넷 (설계: read-models.md §4) ───────────────────────────────────────
+ *   ① 조회는 이 표가 답한다. `twin_events` 에 목차를 얹어 답하지 않는다
+ *   ② **앞으로만 채운다.** 소급하지 않는다 — 새 키가 필요할 때 3,128만 줄을 다시 만들지 않는다
+ *   ③ 준비되지 않은 구간을 화면이 말한다. 비어 있는 것을 「없다」로 그리지 않는다
+ *   ④ 언제든 버릴 수 있다. 사건에서 파생된 값이므로 지워도 사실이 사라지지 않는다
+ *
+ * ── 왜 사건 본문을 베끼지 않나 ──────────────────────────────────────────────
+ * `eventId` 로 원본을 가리키고, 목록을 그리는 데 필요한 값만 함께 둔다(종류·시각·리비전). 본문까지
+ * 베끼면 이 표가 원본만큼 커지고, 원본을 고칠 때 두 곳이 어긋난다.
+ */
+@Entity()
+/*
+ * 이 표의 유일한 목차 — 이 순서가 곧 이 표의 존재 이유다.
+ *
+ * 「이 트윈의 이 대상의 것을 최신순으로 30개」가 목차를 위에서 30줄 읽고 끝난다. 정렬이 없다 —
+ * 거르는 값이 하나이고 그 다음이 시각이기 때문이다.
+ */
+@Index(
+  'ix_twin_subject_event_0',
+  (e: TwinSubjectEvent) => [e.domain, e.instanceId, e.subjectKind, e.subjectId, e.eventTime],
+  { unique: false }
+)
+/* 보관 상한을 지우는 축 — 「이 트윈에서 오래된 줄」을 찾는다(§`twin-subject-writer` 의 정리). */
+@Index('ix_twin_subject_event_1', (e: TwinSubjectEvent) => [e.domain, e.instanceId, e.eventTime], {
+  unique: false
+})
+@ObjectType({ description: 'One row per subject an event refers to — the read model behind entity history.' })
+export class TwinSubjectEvent {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => String, { description: 'Row id.' })
+  readonly id: string
+
+  @ManyToOne(type => Domain)
+  domain: Domain
+
+  @RelationId((e: TwinSubjectEvent) => e.domain)
+  domainId?: string
+
+  @Column()
+  @Field({ description: 'The twin instance this row belongs to.' })
+  instanceId: string
+
+  @Column()
+  @Field({
+    description:
+      'What kind of thing this row points at: item, lot, order, location, equipment or task. The kind is stored as a value so a reader never has to know which event types put what where.'
+  })
+  subjectKind: string
+
+  @Column()
+  @Field({ description: 'Identifier of that thing, within its kind.' })
+  subjectId: string
+
+  /*
+   * **타입 이름을 적지 않는다** — `twin-event.ts` 의 `eventTime` 과 같은 이유다.
+   *
+   * `datetime` 은 sqlite·MySQL 의 이름이고 Postgres 는 `timestamp` 만 안다. 다섯 드라이버에 다
+   * 통하는 이름이 없어서, 이름을 고르는 일을 TypeORM 에 맡긴다(TS 타입 `Date` 에서 고른다).
+   */
+  @Column()
+  @Field({ description: 'When the event happened, by the twin clock. This is the axis the history list is ordered by.' })
+  eventTime: Date
+
+  @Column({ type: 'int' })
+  @Field(type => Int, { description: 'Journal revision of the event — ties this row to its place in the record.' })
+  revision: number
+
+  @Column()
+  @Field({ description: 'Event type, so the list can be drawn without reading the journal row.' })
+  eventType: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Journal row this points at. Null when the journal row has been pruned.' })
+  eventId?: string
+
+  @CreateDateColumn()
+  @Field({ description: 'When this row was written.' })
+  createdAt?: Date
+}

package/server/service/twin-subject/twin-subject-fast-path.ts

@@ -0,0 +1,346 @@
+import { decodeCursor, getRepository } from '@things-factory/shell'
+
+import { TwinEvent } from '../twin-event/twin-event.js'
+import { JOURNAL_COUNT_CAP as COUNT_CAP } from '../twin-event/journal-count.js'
+import { TwinSubjectEvent } from './twin-subject-event.js'
+import { subjectWriteFailures } from './twin-subject-writer.js'
+import { itemResolverFor } from './item-resolver.js'
+import type { SubjectKind } from './event-subjects.js'
+import { readModelShape, type SubjectQueryShape as Shape } from './subject-query-shape.js'
+import { absoluteTime } from '../../engine/read-time.js'
+import { TwinEngine } from '../../engine/index.js'
+
+/*
+ * **화면이 이미 부르는 문에서 파생 테이블을 쓴다** (2026-08-28).
+ *
+ * ── 무엇이 잘못되어 있었나 ──────────────────────────────────────────────────
+ * 대상별 사건 목록(`twin_subject_events`)을 만들고 조회도 새로 열었는데(`twinSubjectHistory`),
+ * 360 화면은 예전부터 `twinEventList` 를 부르고 있었다. 그래서 테이블은 8,382,017줄을 채우고도
+ * 쓰이지 않았고, 화면의 이력 조회는 그대로 64초였다. **자리는 있고 길이 없었다.**
+ *
+ * 새 문으로 옮기라고 화면에 요구하지 않는다. 화면이 이미 서 있는 문 안에서 답을 어디서 가져오는지만
+ * 바꾼다 — 계약(`TwinEventList`)도, 커서도, 응답 모양도 그대로다.
+ *
+ * ── 어떤 물음일 때만 쓰나 ───────────────────────────────────────────────────
+ * 파생 테이블은 「대상 하나를 시각순으로」에 맞춰 생겼다. 그 모양이 아닌 물음은 여기서 답하지 않고
+ * 저널로 보낸다(`null` 을 돌려준다). 좁게 잡는 이유는, 맞지 않는 물음에 억지로 답하면 목록이
+ * 알리지 않고 달라지기 때문이다.
+ *
+ *   쓴다      트윈 하나 · 축 하나(품목·오더·자리·설비) · 시각 내림차순 · 시각 상한(시간여행)까지
+ *   안 쓴다   여러 트윈 · 자유 검색 · 종류 필터 · 상관 식별자 · 그 밖의 정렬
+ *
+ * ── 어디까지 답할 수 있나 ───────────────────────────────────────────────────
+ * 파생 테이블은 만들어진 뒤부터 채워진다. 그보다 앞의 사건은 저널에는 있고 여기에는 없다. 그 경계를
+ * `coveredFrom`(이 트윈의 가장 오래된 파생 줄의 시각)이라 하고, **경계를 넘는 페이지는 저널로 보낸다.**
+ * 커서 모양이 저널 경로와 같으므로 넘기는 자리에서 그냥 이어진다 — 앞은 빠르고, 경계 아래는 느리지만
+ * 온전하다. 없는 것을 「사건이 없다」로 그리는 일은 생기지 않는다.
+ *
+ * 적지 못한 줄이 있으면(`subjectWriteFailures`) 그 창에 구멍이 있다는 뜻이므로 아예 저널로 보낸다.
+ *
+ * 설계: `operato-twin/design/plans/read-models.md`
+ */
+
+export interface FastPathResult {
+  items: TwinEvent[]
+  nextCursor?: string
+  /** 이 트윈에서 파생 테이블이 말할 수 있는 가장 오래된 시각 — 화면이 경계를 말할 수 있게. */
+  coveredFrom?: Date
+  /** 파생 테이블이 저널의 처음까지 덮고 있나 — 아니면 전체 건수를 「모른다」로 낸다. */
+  fullyCovered: boolean
+}
+
+/**
+ * 화면이 건넨 축 값 → 파생 테이블의 키.
+ *
+ * 자리·오더·설비는 화면과 저장이 같은 값을 쓴다. **품목만 다르다**: 화면은 짧게 줄인 것을 들고 있고
+ * (`net/class/product-M1`) 저장된 것은 전체 식별자다. 그 되돌림을 적는 쪽과 **같은 함수**로 한다
+ * (`itemResolverFor`) — 두 벌로 적으면 어느 날 서로 다른 답을 내고, 그때 이력이 빈다.
+ */
+async function canonicalize(domainId: string, instanceId: string, kind: SubjectKind, value: string): Promise<string | null> {
+  if (kind !== 'item') return value
+  const det = await TwinEngine.detail(domainId, instanceId).catch(() => null)
+  const itemOf = det?.model ? itemResolverFor(domainId, instanceId, det.model) : undefined
+  if (!itemOf) return null
+  return itemOf(value) ?? null
+}
+
+/**
+ * 이 트윈에서 파생 테이블이 말할 수 있는 경계와, 저널의 처음까지 덮는지.
+ *
+ * 둘 다 목차만 읽는 질의다(`(domain, instance, event_time)` 의 첫 줄). 그래서 부를 때마다 구해도
+ * 값이 싸고, 저장해 두지 않으므로 실제 데이터와 어긋날 일이 없다.
+ */
+async function coverage(domainId: string, instanceId: string): Promise<{ from?: Date; full: boolean }> {
+  /*
+   * ── **원시 값을 직접 날짜로 읽지 않는다** (2026-08-28 실측) ──────────────────
+   *
+   * `getRawOne` 은 드라이버가 준 값을 그대로 준다. sqlite 의 그 값은 시간대가 없는 문자열
+   * (`2026-08-27 14:37:20.049`)이고, 그것을 `new Date()` 로 읽으면 **한국 시간으로 해석**해
+   * UTC 로 9시간을 뺀다. 실측: 커서의 시각이 9시간 이르게 나가 이어 읽기가 구간을 건너뛰었다.
+   *
+   * `getOne` 은 엔티티로 받으므로 컬럼 변환이 걸린다 — 드라이버가 무엇이든 같은 값이 된다.
+   * 조인이 없으므로 감싸지 않고, 상한이 안쪽에 걸린다(§`twinEvents` 의 실측).
+   */
+  const [sub, journal] = await Promise.all([
+    getRepository(TwinSubjectEvent)
+      .createQueryBuilder('s')
+      .where('s.domain = :domainId', { domainId })
+      .andWhere('s.instanceId = :instanceId', { instanceId })
+      .orderBy('s.eventTime', 'ASC')
+      .limit(1)
+      .getOne()
+      .catch(() => null),
+    getRepository(TwinEvent)
+      .createQueryBuilder('e')
+      .where('e.domain = :domainId', { domainId })
+      .andWhere('e.instanceId = :instanceId', { instanceId })
+      .orderBy('e.eventTime', 'ASC')
+      .limit(1)
+      .getOne()
+      .catch(() => null)
+  ])
+  const from = sub?.eventTime instanceof Date ? sub.eventTime : undefined
+  const oldest = journal?.eventTime instanceof Date ? journal.eventTime : undefined
+  if (!from || Number.isNaN(from.getTime())) return { from: undefined, full: false }
+  const full = !!oldest && !Number.isNaN(oldest.getTime()) && from.getTime() <= oldest.getTime()
+  return { from, full }
+}
+
+/**
+ * 파생 테이블로 한 페이지 — 답할 수 없으면 `null`(부르는 쪽이 저널로 간다).
+ *
+ * 두 걸음이다. ① 파생 테이블에서 리비전 번호를 페이지만큼 읽는다(목차만 읽으므로 정렬이 없다).
+ * ② 그 번호로 저널 줄을 가져온다(`(domain, instance, revision)` 목차의 키 조회 · 50줄).
+ * 두 번째 걸음이 필요한 이유는 화면이 저널 줄의 내용(`payload`·`bizStep`…)을 그리기 때문이다 —
+ * 파생 테이블은 목차이지 사실의 집이 아니다.
+ */
+export async function subjectFastPage(
+  domainId: string,
+  instanceId: string,
+  shape: Shape,
+  limit: number,
+  after?: string
+): Promise<FastPathResult | null> {
+  /* 적지 못한 줄이 있으면 이 창에 구멍이 있다 — 그때는 온전한 쪽(저널)으로 보낸다. */
+  if (subjectWriteFailures(domainId, instanceId) > 0) return null
+
+  const subjectId = await canonicalize(domainId, instanceId, shape.kind, shape.value)
+  if (!subjectId) return null
+
+  const cov = await coverage(domainId, instanceId)
+  if (!cov.from) return null
+
+  /* 이어 읽기 지점 — 저널 경로와 **같은 커서**를 읽는다(`[eventTime, revision]`). */
+  let cursor: { at: Date; revision: number } | null = null
+  if (after) {
+    cursor = decodeJournalCursor(after)
+    if (!cursor) return null
+  }
+
+  /*
+   * 경계를 넘는 페이지는 여기서 답하지 않는다. 파생 테이블에는 그 아래가 없으므로, 답하면 목록이
+   * 「여기서 끝」이라고 말하게 된다. 저널로 보내면 커서가 그대로 이어진다.
+   *
+   * 이어 읽기 지점이 경계와 **같을** 때도 보낸다 — 그 커서는 아래에서 우리가 직접 만든 「경계 아래를
+   * 읽어라」는 표시이고(§`boundaryCursor`), 여기서 받으면 같은 페이지를 되풀게 된다.
+   */
+  if (cursor && cursor.at.getTime() <= cov.from.getTime()) return null
+  if (shape.untilTime && shape.untilTime.getTime() < cov.from.getTime()) return null
+
+  const qb = getRepository(TwinSubjectEvent)
+    .createQueryBuilder('s')
+    .select('s.revision', 'revision')
+    .where('s.domain = :domainId', { domainId })
+    .andWhere('s.instanceId = :instanceId', { instanceId })
+    .andWhere('s.subjectKind = :kind', { kind: shape.kind })
+    .andWhere('s.subjectId = :subjectId', { subjectId })
+  if (shape.fromTime) qb.andWhere('s.eventTime >= :fromTime', { fromTime: shape.fromTime })
+  if (shape.untilTime) qb.andWhere('s.eventTime <= :untilTime', { untilTime: shape.untilTime })
+  if (cursor) {
+    /* 시각이 같은 줄이 여럿이므로 리비전으로 갈라 이어 읽는다 — 건너뛰거나 되풀지 않게. */
+    qb.andWhere('(s.eventTime < :curAt OR (s.eventTime = :curAt AND s.revision < :curRev))', {
+      curAt: cursor.at,
+      curRev: cursor.revision
+    })
+  }
+  const picked = await qb
+    .orderBy('s.eventTime', 'DESC')
+    .addOrderBy('s.revision', 'DESC')
+    .limit(limit)
+    .getRawMany<{ revision: number }>()
+    .catch(() => null)
+  if (!picked) return null
+  if (!picked.length) {
+    /* 이 대상의 줄이 경계 안에 없다 — 경계 아래는 저널만 안다. 그 사실을 커서로 넘긴다. */
+    return { items: [], nextCursor: cov.full ? undefined : boundaryCursor(cov.from), coveredFrom: cov.from, fullyCovered: cov.full }
+  }
+
+  const revisions = picked.map(p => Number(p.revision)).filter(n => Number.isFinite(n))
+  const rows = await getRepository(TwinEvent)
+    .createQueryBuilder('e')
+    .where('e.domain = :domainId', { domainId })
+    .andWhere('e.instanceId = :instanceId', { instanceId })
+    .andWhere('e.revision IN (:...revisions)', { revisions })
+    .getMany()
+    .catch(() => null)
+  if (!rows) return null
+
+  /*
+   * 저널 줄을 파생 테이블이 정한 순서로 되돌린다. `IN` 조회는 순서를 약속하지 않으므로 여기서
+   * 세운다 — 50줄이라 값이 없다.
+   */
+  const byRevision = new Map(rows.map(r => [Number((r as any).revision), r]))
+  const items = revisions.map(r => byRevision.get(r)).filter(Boolean) as TwinEvent[]
+
+  /*
+   * 지워진 저널 줄은 목차에 남아 있을 수 있다(보관 정리가 저널을 먼저 지운 창). 그 차이를 세어
+   * 페이지가 짧아진 것을 알린다 — 그러나 여기서는 커서만 정확히 이어 주면 되고, 잃은 사실은 없다.
+   */
+  /*
+   * ── 다음 지점 ───────────────────────────────────────────────────────────────
+   * 페이지가 꽉 찼으면 이어 읽기 지점은 이번 페이지의 마지막 줄이다(저널 경로와 같은 축).
+   * **시각은 저널 줄에서 가져온다** — 목차의 원시 값을 직접 읽으면 시간대가 어긋난다(§`coverage`).
+   *
+   * 짧게 끝났으면 이 대상의 줄을 경계 안에서 다 냈다는 뜻이다. 그때 「없다」로 끝내면 안 된다 —
+   * 경계 아래에 저널만 아는 사건이 있을 수 있고, 그것을 끝으로 그리면 목록이 알리지 않고 잘린다.
+   * 그래서 **경계 아래를 읽으라는 커서**를 낸다. 저널이 그 다음 페이지를 답한다(느리지만 온전하다).
+   *
+   * 파생 테이블이 저널의 처음까지 덮고 있으면 아래에 아무것도 없으므로 그때만 끝이다.
+   */
+  let edge: { at: Date; revision: number } | null = null
+  if (picked.length === limit) {
+    /* 지워진 저널 줄은 목차에 남아 있을 수 있다 — 줄이 있는 마지막 것에서 지점을 만든다. */
+    for (let i = revisions.length - 1; i >= 0; i--) {
+      const row: any = byRevision.get(revisions[i])
+      if (row?.eventTime instanceof Date && !Number.isNaN(row.eventTime.getTime())) {
+        edge = { at: row.eventTime, revision: revisions[i] }
+        break
+      }
+    }
+  }
+  const nextCursor = edge ? encodeJournalCursor(edge.at, edge.revision) : cov.full ? undefined : boundaryCursor(cov.from)
+
+  return { items, nextCursor, coveredFrom: cov.from, fullyCovered: cov.full }
+}
+
+/**
+ * 「경계보다 오래된 것을 읽어라」는 지점.
+ *
+ * 저널 경로의 커서 조건은 `(시각 < v) 또는 (시각 = v 그리고 리비전 < v2)` 다. 그래서 리비전 자리에
+ * 0 을 두면 뒷절이 성립하지 않고 **시각이 경계보다 오래된 것만** 남는다 — 경계에 있는 줄은 이미
+ * 냈으므로 그것이 정확히 남은 구간이다. 이 커서를 다시 받으면 이 경로는 물러난다(위의 경계 검사).
+ */
+function boundaryCursor(from: Date): string {
+  return encodeJournalCursor(from, 0)
+}
+
+/**
+ * 목록 계약 한 페이지를 파생 테이블로 답한다 — 답할 수 없으면 `null`(부르는 쪽이 저널로 간다).
+ *
+ * ── 전체 건수와 「더 있나」 ──────────────────────────────────────────────────
+ * 두 칸을 함께 정직하게 채워야 한다. 화면은 전체 건수를 모를 때 `capped` 로 「더 있나」를 판단한다
+ * (`hasMore`). 그래서 건수를 모르면서 `capped` 를 내리면 **목록이 알리지 않고 끝난 것처럼 보인다.**
+ *
+ *   파생 테이블이 저널의 처음까지 덮는다  →  정확한 전체 건수 · capped 내림
+ *   덮지 못한다(앞이 저널에만 있다)       →  전체 건수 모름 · capped 올림(가진 수는 하한이다)
+ */
+export async function readModelPage(domainId: string, instanceId: string, params: any, limit: number): Promise<TwinEventListShape | null> {
+  const shape = readModelShape(params, params?.sortings ?? [])
+  if (!shape) return null
+
+  const page = await subjectFastPage(domainId, instanceId, shape, limit, params?.pagination?.after ?? undefined)
+  if (!page) return null
+
+  let total: number | undefined
+  if (page.fullyCovered) {
+    const counted = await countSubjectRows(domainId, instanceId, shape)
+    if (counted !== null && counted <= COUNT_CAP) total = counted
+  }
+  /* 정확한 수를 낼 수 없으면 「모른다」로 내고, 가진 수가 하한임을 함께 말한다. */
+  const capped = total === undefined
+
+  return {
+    items: page.items,
+    total,
+    capped,
+    countCap: COUNT_CAP,
+    nextCursor: page.nextCursor,
+    oldestRevision: await oldestJournalRevision(domainId, instanceId)
+  }
+}
+
+/** 목록 계약이 돌려주는 모양 — 저널 경로와 같은 칸을 채운다. */
+export interface TwinEventListShape {
+  items: TwinEvent[]
+  total?: number
+  capped: boolean
+  countCap: number
+  nextCursor?: string
+  oldestRevision?: number
+}
+
+/** 이 대상의 사건 수 — 목차만 읽는다(`(도메인, 트윈, 종류, 식별자, 시각)` 의 앞부분). */
+async function countSubjectRows(domainId: string, instanceId: string, shape: Shape): Promise<number | null> {
+  const subjectId = await canonicalize(domainId, instanceId, shape.kind, shape.value)
+  if (!subjectId) return null
+  const qb = getRepository(TwinSubjectEvent)
+    .createQueryBuilder('s')
+    .where('s.domain = :domainId', { domainId })
+    .andWhere('s.instanceId = :instanceId', { instanceId })
+    .andWhere('s.subjectKind = :kind', { kind: shape.kind })
+    .andWhere('s.subjectId = :subjectId', { subjectId })
+  if (shape.fromTime) qb.andWhere('s.eventTime >= :fromTime', { fromTime: shape.fromTime })
+  if (shape.untilTime) qb.andWhere('s.eventTime <= :untilTime', { untilTime: shape.untilTime })
+  return qb.getCount().catch(() => null)
+}
+
+/**
+ * 이 트윈에 남아 있는 가장 오래된 리비전 — 보관 정리로 앞이 지워졌는지 화면이 말할 수 있게.
+ * 저널 경로가 내는 것과 같은 값이고 같은 이유다(없었던 것과 지워진 것은 다른 사실이다).
+ */
+async function oldestJournalRevision(domainId: string, instanceId: string): Promise<number | undefined> {
+  const first = await getRepository(TwinEvent)
+    .createQueryBuilder('e')
+    .select('e.revision', 'revision')
+    .where('e.domain = :domainId', { domainId })
+    .andWhere('e.instanceId = :instanceId', { instanceId })
+    .orderBy('e.revision', 'ASC')
+    .limit(1)
+    .getRawOne<{ revision: unknown }>()
+    .catch(() => null)
+  const at = Number(first?.revision)
+  return Number.isFinite(at) && at > 0 ? at : undefined
+}
+
+/**
+ * 저널 경로와 **같은 축의** 커서를 만든다 — `[eventTime, revision]`.
+ *
+ * 시각이 같은 줄들 사이에서 무엇이 앞인지 가리는 축이 두 경로에서 같아야 한다. 다르면 한 목록을
+ * 나눠 답하는 자리에서 본 줄이 또 나온다(실측: 120건 중 15건). 저널 경로도 트윈 하나를 볼 때는
+ * `revision` 으로 가린다(§`cursorTiebreak`).
+ */
+function encodeJournalCursor(at: Date, revision: number): string {
+  return Buffer.from(JSON.stringify([at, revision]), 'utf8').toString('base64url')
+}
+
+/**
+ * 커서를 파생 테이블이 쓸 수 있는 지점으로 읽는다 — `[eventTime, revision]`.
+ *
+ * 예전에는 커서에 저널 줄의 `id` 가 실려 있어서 그 줄을 한 번 읽어 리비전을 얻었다. 그 방식은
+ * **지워진 줄에서 어긋났다**: 보관 정리가 저널을 지우면 리비전을 얻지 못하고, 얻은 리비전이
+ * 이어 읽기 지점의 시각과 다른 줄의 것일 수 있었다. 이제 두 경로가 같은 축을 쓰므로 커서에 실린
+ * 값을 그대로 읽는다 — 조회도 필요 없다.
+ */
+function decodeJournalCursor(cursor: string): { at: Date; revision: number } | null {
+  let values: unknown[]
+  try {
+    values = decodeCursor(cursor)
+  } catch {
+    return null
+  }
+  if (values.length !== 2) return null
+  const at = absoluteTime(values[0])
+  const revision = Number(values[1])
+  if (!at || !Number.isFinite(revision)) return null
+  return { at, revision }
+}