@things-factory/headless-twin 10.1.278 → 10.1.279

package/test/journal-read-discipline.test.ts

@@ -1,186 +0,0 @@
-/*
- * ★ 저널을 통째로 읽는 자리는 **코드에 그 이유가 적혀 있어야 한다** — 소스 규율 검사.
- *
- * ── 왜 이 검사가 필요한가 (2026-08-20) ──────────────────────────────────────
- * `TwinEngine.timeRange` 는 min/max **두 수**를 구하려고 공간의 인스턴스마다 저널을 `find()` 로 전부
- * 실어 왔다. 개발 서버에서 한 트윈이 275,882행 · `payload` 131MB 였고, 화면 상단의 컨텍스트 띠가 그
- * 함수를 **4초마다** 불렀다. 프로세스 CPU 81~152%, 아무 일도 하지 않는 질의가 8~14초였다.
- *
- * **사람 리뷰가 이것을 잡지 못한 이유는 코드가 맞았기 때문이다.** min/max 는 정확히 나왔다. 틀린 것은
- * 답이 아니라 비용이고, 비용은 읽어서는 보이지 않는다. 그래서 사람에게 다시 맡기지 않고 기계에 맡긴다.
- *
- * ── 규율 ────────────────────────────────────────────────────────────────────
- * 저널(`TwinEvent`)을 `find()` 로 읽는 자리는 둘 중 하나여야 한다.
- *  ① **상한이 있다**(`take:`) — 목록·표본처럼 화면이 쓰는 만큼만 읽는 경우.
- *  ② **폴드다** — 사실을 하나씩 계산하는 것이 목적이라 그 구간의 행이 필요한 경우. 이때는 바로 앞에
- *     `journal-fold:` 로 시작하는 주석을 두어 **왜 필요한지**, 그리고 상한이 없다면 **없어질 조건**을
- *     함께 적는다.
- *
- * 둘 다 아니면 이 검사가 빨개진다. 「두 수만 필요한데 표를 다 읽는」 코드가 다시 들어오는 것을 막는
- * 자리가 여기다. 집계(MIN/MAX/COUNT)는 DB 가 하고 행은 실어 오지 않는다.
- */
-import { test } from 'node:test'
-import assert from 'node:assert/strict'
-import { readFileSync, readdirSync, statSync } from 'node:fs'
-import { join } from 'node:path'
-
-import { guardRoots } from './guard-roots.ts'
-
-/** 훑는 곳 — 저널을 읽을 수 있는 층 둘. */
-const ROOTS = guardRoots(import.meta.url, ['../server'])
-
-const READ = 'getRepository(TwinEvent)'
-/** 폴드라고 밝히는 표식. 이유를 함께 적는 것이 이 표식의 값이다. */
-const FOLD_PRAGMA = 'journal-fold:'
-/** 표식을 찾아 볼 범위 — 바로 앞 주석 블록. 멀리 두면 무엇에 붙은 표식인지 알 수 없다. */
-const PRAGMA_LOOKBACK = 900
-
-/** 주석을 지운 소스 — 규율을 **설명하는 글**이 규율 위반으로 잡히지 않게. */
-function stripComments(src: string): string {
-  return src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^[ \t]*\/\/.*$/gm, '')
-}
-
-function sources(dir: string): string[] {
-  let entries: string[]
-  try {
-    entries = readdirSync(dir)
-  } catch {
-    return []
-  }
-  return entries.flatMap(f => {
-    const p = join(dir, f)
-    return statSync(p).isDirectory() ? sources(p) : p.endsWith('.ts') && !p.endsWith('.d.ts') ? [p] : []
-  })
-}
-
-interface Site {
-  file: string
-  line: number
-  bounded: boolean
-  fold: boolean
-}
-
-/** 저널을 `find()` 로 읽는 자리들. 쓰기(`insert`/`save`)와 집계(`createQueryBuilder`)는 대상이 아니다. */
-function journalFindSites(): Site[] {
-  const out: Site[] = []
-  for (const root of ROOTS) {
-    for (const f of sources(root)) {
-      const src = readFileSync(f, 'utf-8')
-      let at = src.indexOf(READ)
-      while (at >= 0) {
-        const tail = src.slice(at + READ.length, at + READ.length + 600)
-        /* 이 자리가 어떤 호출인가 — 첫 메서드만 본다. */
-        const call = /^\s*\.?\s*(find|findOne|count|countBy|createQueryBuilder|save|insert|delete|create)\b/.exec(tail)
-        if (call && call[1] === 'find') {
-          /* 옵션 객체 안에 상한이 있나 — 괄호 균형까지 보지 않고 넉넉히 잘라 본다(실패 시 폴드 표식이 받는다). */
-          const opts = tail.slice(0, 500)
-          const before = src.slice(Math.max(0, at - PRAGMA_LOOKBACK), at)
-          out.push({
-            file: f.slice(root.length + 1),
-            line: src.slice(0, at).split('\n').length,
-            bounded: /\btake\s*:/.test(opts),
-            fold: before.includes(FOLD_PRAGMA)
-          })
-        }
-        at = src.indexOf(READ, at + 1)
-      }
-    }
-  }
-  return out
-}
-
-test('저널을 통째로 읽는 자리는 폴드라고 밝히고 이유를 적는다', () => {
-  const bare = journalFindSites()
-    .filter(s => !s.bounded && !s.fold)
-    .map(s => `${s.file}:${s.line}`)
-
-  assert.deepEqual(
-    bare,
-    [],
-    `이유 없이 저널 전체를 읽는 자리 ${bare.length}곳:\n  ${bare.join('\n  ')}\n\n` +
-      `둘 중 하나로 만든다.\n` +
-      `  ① 화면이 쓰는 만큼만 읽는다면 \`take:\` 를 준다.\n` +
-      `  ② 사실을 계산하는 것이 목적이라면 바로 앞에 \`journal-fold:\` 주석으로 왜 행이 필요한지,\n` +
-      `     상한이 없다면 그 예외가 없어질 조건까지 적는다.\n\n` +
-      `수 몇 개만 필요하다면 셋째 길이 맞다: 집계는 DB 가 한다(MIN/MAX/COUNT + createQueryBuilder).\n` +
-      `\`timeRange\` 가 min/max 두 수를 구하려고 275,882행·payload 131MB 를 4초마다 파싱했던 자리다.`
-  )
-})
-
-test('검사가 실제로 저널 읽기를 보고 있다 — 대상이 사라지면 초록이 거짓이 된다', () => {
-  const sites = journalFindSites()
-
-  /*
-   * ── 문턱을 셋에서 둘로 내렸다 (2026-08-28) ─────────────────────────────────
-   * 자리 하나를 **질의 빌더로 옮겨서** 줄었다(계보 조회 — 관계로 물어 두 단계 질의가 되고 `take` 가
-   * 있어도 안쪽에 상한이 없던 자리다). 그 방향이 이 검사가 바라는 방향이므로 문턱을 따라 내린다.
-   *
-   * 이 단정의 뜻은 「자리가 많아야 한다」가 아니라 **「검사가 무언가를 보고 있어야 한다」**다. 남은 둘도
-   * 옮겨지면 이 시험이 빨개지는데, 그때가 바로 사람이 알아야 하는 순간이다 — 검사가 아무것도 보지 않는
-   * 채로 초록이면 그 초록이 거짓이다. 그때는 검사의 패턴을 질의 빌더 쪽으로 옮긴다.
-   */
-  assert.ok(
-    sites.length >= 2,
-    `저널 \`find()\` 를 ${sites.length}곳 찾았다 — 둘보다 적으면 이 검사가 보는 대상이 없어졌다는 뜻이다. ` +
-      `호출을 질의 빌더로 옮겼다면 이 검사의 패턴도 그쪽으로 옮긴다(리포지토리를 변수에 담아 부르는 ` +
-      `형태도 함께 본다).`
-  )
-})
-
-test('시각축은 집계로 답한다 — 행을 실어 오는 방식으로 되돌아가지 않는다', () => {
-  /*
-   * `timeRange` 만은 이름으로 못 박는다. 이 함수가 이 결함의 출처이고, 되돌아가도 **답은 맞기 때문에**
-   * 결과를 보는 시험으로는 잡히지 않는다.
-   */
-  const src = readFileSync(new URL('../server/engine/twin-engine.ts', import.meta.url).pathname, 'utf-8')
-  const at = src.indexOf('static async timeRange(')
-  assert.ok(at > 0, 'timeRange 를 찾지 못했다 — 이름이 바뀌면 이 검사도 함께 옮긴다')
-
-  const body = src.slice(at, at + 2500)
-  assert.ok(body.includes('MIN(e.eventTime)'), '가장 이른 시각은 DB 가 고른다')
-  assert.ok(body.includes('MAX(e.eventTime)'), '가장 늦은 시각도 그렇다')
-  assert.ok(!body.includes('getRepository(TwinEvent).find('), '저널을 행 단위로 실어 오지 않는다')
-})
-
-/*
- * ── 세는 것도 읽는 것이다 (2026-08-22 실측) ─────────────────────────────────
- * 위 규율은 **행을 실어 오는 것**을 봤다. 그런데 `getManyAndCount()` 는 행을 싣지 않으면서도 조건에
- * 맞는 행을 **전부 센다**. 실측: 저널 358만 행인 트윈에서 한 번에 5.32초, 상한 1만이면 0.04초.
- * 이력 화면을 열 때마다 그것을 물었고 그 5초 동안 이벤트 루프가 다른 요청을 처리하지 못했다.
- *
- * 그래서 저널에는 **상한 없는 세기를 두지 않는다.** 정확한 수를 모르는 것은 사실이므로 그때는
- * 「모른다」로 낸다(목록 규약의 `capped`) — 상한값을 전체로 적으면 화면이 거짓을 말한다.
- */
-test('저널을 상한 없이 세지 않는다 — 답은 맞지만 비용이 틀린 자리', () => {
-  /*
-   * **주석과 남의 표를 세지 않는다.** 처음 만든 검사는 「파일이 `TwinEvent` 를 언급하고 어딘가에
-   * `.count(` 가 있으면」 이었다. 그래서 공간·구조·대표표현을 세는 자리와 **이 규율을 설명하는 주석**
-   * 까지 잡았다 — 거짓 경보는 참 경보를 죽인다. 규칙은 하나다: **저널 저장소에서 세는 자리**만 본다.
-   */
-  const offenders: string[] = []
-  for (const file of ROOTS.flatMap(r => sources(r))) {
-    const src = stripComments(readFileSync(file, 'utf-8'))
-    for (const m of src.matchAll(/getRepository\(TwinEvent\)|repository: getRepository\(TwinEvent\)/g)) {
-      const after = src.slice(m.index ?? 0, (m.index ?? 0) + 900)
-      const counted = after.match(/getManyAndCount\(|getCount\(|\.count\(/)
-      if (!counted) continue
-      /* 상한이 함께 적혀 있으면 규율을 지킨 것이다(상한까지만 센다). */
-      if (/take\(|COUNT_CAP/.test(after.slice(0, (counted.index ?? 0) + 80))) continue
-      offenders.push(`${file.split('/packages/')[1]}  ${counted[0]}`)
-    }
-  }
-  assert.deepEqual(
-    offenders,
-    [],
-    `저널을 상한 없이 세는 자리가 있다 — 상한까지만 세고 넘으면 「모른다」로 낸다:\n  ${offenders.join('\n  ')}`
-  )
-})
-
-test('건수 상한이 값으로 선언돼 있고, 넘으면 전체를 비운다', () => {
-  const src = readFileSync(new URL('../server/service/twin-journal/twin-journal-query.ts', import.meta.url).pathname, 'utf-8')
-  assert.match(src, /const COUNT_CAP = JOURNAL_COUNT_CAP/, '상한은 저널 세기의 문에서 온다 — 값이 두 곳에 흩어지지 않게')
-  assert.match(src, /take\(COUNT_CAP \+ 1\)/, '상한을 넘었는지 알려면 하나 더 읽어야 한다')
-  /* 상한을 넘으면 **전체를 비운다** — 상한값을 전체로 적으면 화면이 거짓을 말한다. */
-  assert.match(src, /capped \? undefined : counted\.length/)
-  assert.match(src, /capped/, '넘었다는 사실을 함께 낸다(알리지 않고 자르지 않는다)')
-})

package/test/journal-retention.test.ts

@@ -1,275 +0,0 @@
-/*
- * ★ 저널 보존 — **선언이 있을 때만 지운다. 그리고 도는 트윈에서만 체크포인트를 상한으로 본다.**
- *
- * ── 왜 필요한가 (2026-08-22 실측) ───────────────────────────────────────────
- * 개발 저널이 시간당 **581,794행 · 0.85GB**(하루 20GB)로 자랐다. 데모 MES 트윈 셋이 전체의 **97%** 를
- * 만들고 지우는 것이 없었다.
- *
- * ── 체크포인트를 전제 조건으로 두었던 것이 결함이었다 (2026-08-27) ──────────
- * 예전 규율은 「체크포인트가 없는 인스턴스는 건드리지 않는다」였다. 근거는 「그때 저널이 유일한 복구
- * 수단이다」였고, 그 근거가 틀렸다. 트윈이 자기 저널과 어떤 관계인지는 `restartPolicy` 가 선언한다.
- *
- *   resync   연결된 시스템에서 다시 읽는다   저널은 복구 수단이 아니다
- *   reset    씨앗부터 다시 돌린다            저널은 복구 수단이 아니다
- *   resume   저널을 이어 세운다              보관된 구간에서 세운다
- *
- * 셋 다 보관 기간 밖의 사건을 요구하지 않는다. 보존 기간을 7일로 선언한 것이 곧 「7일 전 상태로는
- * 세우지 않는다」는 뜻이다. 그 전제 때문에 멈춘 트윈 셋에 2,900만 행이 영구히 남았다.
- *
- * 체크포인트가 남는 일은 하나다. **도는 트윈**은 메모리에서 이어 집계하므로, 체크포인트가 아직 반영하지
- * 못한 사건을 지우면 그 구간이 어디에도 없어진다. 그래서 도는 트윈에서만 그 리비전을 상한으로 쓴다.
- *
- * ── 이 테스트가 무엇을 재는가 ───────────────────────────────────────────────
- * DB 를 띄우지 않는다. 이 규율은 **조건을 어떻게 세우나**에 있고 그것은 순수하게 확인할 수 있다.
- */
-import { test } from 'node:test'
-import assert from 'node:assert/strict'
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
-
-const ENGINE = join(import.meta.dirname, '..', 'server', 'engine', 'twin-engine.ts')
-const src = readFileSync(ENGINE, 'utf8')
-
-/** `pruneJournal` 본문만 — 다른 자리의 조건이 섞여 판정이 흐려지지 않게. */
-function pruneBody(): string {
-  const at = src.indexOf('static async pruneJournal')
-  assert.ok(at > 0, 'pruneJournal 이 있어야 한다')
-  const rest = src.slice(at)
-  const end = rest.indexOf('\n  /** 보존 정리 주기 기동')
-  return rest.slice(0, end === -1 ? 4000 : end)
-}
-
-test('선언이 없으면 아무것도 지우지 않는다 — 기본값은 없음이다', () => {
-  /* 계약의 기본값 — 여기에 숫자가 박히면 아무도 정하지 않은 채로 지워진다. */
-  assert.match(
-    src,
-    /static JOURNAL_RETENTION_DAYS\?: number = undefined/,
-    '보존 기간의 기본값은 undefined 여야 한다(알리지 않고 지우는 것보다 알리지 않고 쌓는 편이 낫다)'
-  )
-  /* 그리고 그 값이 없으면 즉시 돌아간다. */
-  assert.match(pruneBody(), /if \(!days \|\| days <= 0\) return/, '선언이 없으면 지우지 않고 돌아간다')
-})
-
-test('★ 체크포인트는 상한이지 전제 조건이 아니다 — 없다는 이유로 건너뛰지 않는다', () => {
-  const body = pruneBody()
-  /*
-   * 한 줄이 이 규율의 전부다. 있으면 그 리비전이 상한이고, 없으면 상한이 없다.
-   *
-   * 예전에는 없으면 그 트윈을 건너뛰었다. 그래서 멈춘 트윈 셋에 2,900만 행이 영구히 남았다 —
-   * 멈춘 트윈은 체크포인트를 다시 쓸 주체가 없어서 만료된 뒤 영원히 조건을 못 넘긴다.
-   */
-  assert.match(
-    body,
-    /const upTo = at > 0 \? at : Number\.MAX_SAFE_INTEGER/,
-    '체크포인트가 없으면 상한 없이 지운다'
-  )
-  assert.doesNotMatch(body, /if \(!upTo\)[\s\S]{0,200}?continue/, '없다는 이유로 건너뛰지 않는다')
-  assert.doesNotMatch(body, /skipped/, '건너뛰는 갈래가 아예 없다')
-})
-
-test('지우는 조건이 넷 다 있다 — 하나라도 빠지면 지나친 삭제가 된다', () => {
-  const body = pruneBody()
-  for (const [what, re] of [
-    ['도메인', /domain_id = :domainId/],
-    ['인스턴스', /instance_id = :instanceId/],
-    ['체크포인트 리비전 이하(도는 트윈에서는 상한, 멈춘 트윈에서는 무한)', /revision <= :upTo/],
-    ['보존 기간 이전(실제 시계)', /created_at < :cutoff/]
-  ] as [string, RegExp][]) {
-    assert.match(body, re, `${what} 조건이 있어야 한다`)
-  }
-  /* 시각을 모르는 옛 행은 「오래됐다」로 읽지 않는다. */
-  assert.match(body, /created_at IS NOT NULL/, '시각이 빈 행은 지우지 않는다')
-  /*
-   * **`event_time` 을 기준으로 쓰지 않는다** — 그것은 트윈의 시계다(실측: order-check 의 가장 늦은
-   * eventTime 이 2027-06-08 로 실제보다 10개월 앞). 보존은 저장 나이의 문제이고 그것은 실제 시계다.
-   */
-  assert.doesNotMatch(body, /event_time\s*<\s*:cutoff/, '도메인 시각을 보존 기준으로 쓰지 않는다')
-})
-
-test('도메인의 정책이 프로세스 기본값보다 먼저다 — 그리고 엔진은 그것이 어디서 오는지 모른다', () => {
-  const body = pruneBody()
-  /*
-   * 보존 기간은 **테넌트의 정책**이다(한 고객은 30일, 다른 고객은 7일). 그래서 도메인에 먼저 묻고,
-   * 답이 없을 때만 프로세스 기본값으로 내려간다. 순서가 뒤집히면 설정 화면에서 고친 값이 먹지 않는다.
-   */
-  assert.match(body, /this\.retentionDaysOf\(domainId\)/, '도메인에 먼저 묻는다')
-  assert.match(body, /perDomain \?\? this\.JOURNAL_RETENTION_DAYS/, '도메인 답이 없을 때만 프로세스 기본값이다')
-  /*
-   * 그리고 그 답이 **어디서 오는지 엔진은 모른다** — 시임일 뿐이다. 엔진이 `Setting` 을 직접 읽으면
-   * 커널의 호스트가 화면 관심사를 알게 된다(방향이 거꾸로다).
-   */
-  assert.doesNotMatch(src, /from '@things-factory\/setting-base'/, '엔진은 Setting 을 알지 않는다')
-})
-
-test('★ 보존 기간을 스냅샷 TTL 로 올리지 않는다 — 두 값은 다른 것을 정한다', () => {
-  /*
-   * 예전에는 `max(보존 기간, 스냅샷 TTL)` 이었다. 둘 다 7일이라 상향은 없었지만, 그 식은 두 값을 묶어
-   * 놓아서 보존 기간을 줄이면 스냅샷 TTL 이 따라오게 만든다.
-   *
-   *   보존 기간      이력을 며칠 두나
-   *   스냅샷 TTL     빠르게 세우기 위한 저장본이 며칠 사나
-   *
-   * 저장본이 만료되어도 트윈은 보관된 구간에서 세워진다. 그래서 보존 기간이 더 짧아도 성립한다.
-   */
-  const body = pruneBody()
-  assert.doesNotMatch(body, /Math\.max\(days, minDays\)/, '두 값을 묶지 않는다')
-  assert.match(body, /const effectiveDays = days/, '선언한 보존 기간을 그대로 쓴다')
-})
-
-test('★ 멈출 때는 만료 없이 적는다 — 그러지 않으면 7일 뒤 그 상태를 아는 것이 없다', () => {
-  /*
-   * 멈춘 트윈은 아무도 스냅샷을 다시 쓰지 않아서 7일 뒤 만료된다. 멈추는 순간이 그 상태가 메모리에
-   * 있는 마지막 순간이므로 그때 만료 없이 적는다. 그러면 다시 뜰 때 보관된 구간을 계산하지 않아도 된다.
-   */
-  assert.match(src, /static SNAPSHOT_KEEP_S = /, '만료 없이 두는 기간에 이름이 있어야 한다')
-  const at = src.indexOf('static async stop(')
-  assert.ok(at > 0, 'stop 이 있어야 한다')
-  const stopBody = src.slice(at, at + 1600)
-  assert.match(stopBody, /persistSnapshot\(domainId, id, true\)/, '멈출 때는 만료 없이 적는다')
-  assert.match(src, /keepForever \? this\.SNAPSHOT_KEEP_S : this\.SNAPSHOT_TTL_S/, '그 값이 실제로 쓰인다')
-})
-
-test('지운 것을 말한다 — 알리지 않고 줄어든 저널은 없었던 일과 구별되지 않는다', () => {
-  const body = pruneBody()
-  assert.match(body, /journal pruned/, '지운 건수를 로그에 남긴다')
-  assert.match(body, /revision ≤/, '어디까지 지웠는지 함께 남긴다')
-})
-
-test('raw SQL 을 쓰지 않는다 — 드라이버 다섯을 다 지나야 한다', () => {
-  const body = pruneBody()
-  assert.doesNotMatch(body, /\.query\(/, '드라이버 방언을 직접 적지 않는다')
-  assert.match(body, /createQueryBuilder\(\)[\s\S]{0,80}\.delete\(\)/, '조건 삭제는 쿼리빌더로 한다')
-})
-
-test('선언도 없고 물을 길도 없으면 주기 정리를 걸지 않는다', () => {
-  const at = src.indexOf('static startRetentionLoop')
-  assert.ok(at > 0, 'startRetentionLoop 이 있어야 한다')
-  const body = src.slice(at, at + 900)
-  /*
-   * 조건이 **둘**이다. 프로세스 기본값(`JOURNAL_RETENTION_DAYS`)만 보면 안 된다 — 도메인마다 다른 값을
-   * 앱이 답하는 시임(`retentionDaysOf`)이 있고, 그것이 심겨 있으면 기본값이 없어도 걸어야 한다
-   * (그 도메인이 자기 값을 가질 수 있다). 반대로 **둘 다 없으면 물을 곳이 없으므로** 걸지 않는다.
-   *
-   * 기본값만 보게 두면 시임만 심은 배포에서 정리가 알리지 않고 돌지 않는다 — 「보존을 켰는데 왜 안 줄어드나」.
-   */
-  assert.match(
-    body,
-    /if \(!this\.JOURNAL_RETENTION_DAYS && !this\.retentionDaysOf\) return/,
-    '기본값도 없고 도메인 시임도 없을 때만 타이머를 걸지 않는다'
-  )
-  /* 타이머가 프로세스를 붙잡지 않게 — 지우는 일이 종료를 막을 이유가 없다. */
-  assert.match(body, /unref/, '타이머는 unref 한다')
-})
-
-/*
- * ★ 나눠서 지운다 — 한 문장으로 통째 지우면 그동안 호스트가 멈춘다.
- *
- * 실측(2026-08-25 · 개발 환경 44GB): 보관 기간 7일에 13일치가 쌓여 있었고, 그 밀린 몫이 한 번에
- * 나왔다. 한 번의 지우기가 74초·79초였고 그 뒤에 한 줄짜리 `domains` 조회가 67초로 찍혔다 — 그
- * 질의의 문제가 아니라 줄을 선 값이다. sqlite 는 쓰기가 하나다.
- *
- * 이 테스트는 소스를 전수 조회해 규율을 지킨다: 배치 경계를 먼저 찾는가 · 한 창의 시간 상한이 있는가 ·
- * 배치 사이에 루프를 비워 주는가. 실제 지우기는 큰 기록이 있어야 재현되므로 여기서 재지 않는다.
- */
-test('★ 지우기를 배치로 나눈다 — 쓰기 잠금을 한 번에 오래 잡지 않는다', () => {
-  const src = readFileSync(ENGINE, 'utf8')
-  assert.ok(/JOURNAL_PRUNE_BATCH\s*=\s*[0-9_]+/.test(src), '한 배치의 행 수가 이름을 갖고 있어야 한다')
-  assert.ok(/JOURNAL_PRUNE_BUDGET_MS\s*=\s*[0-9_]+/.test(src), '한 창의 시간 상한이 이름을 갖고 있어야 한다')
-  const prune = src.slice(src.indexOf('static async pruneJournal'))
-  const body = prune.slice(0, prune.indexOf('static startRetentionLoop'))
-  assert.ok(body.includes('JOURNAL_PRUNE_BATCH'), '배치 경계를 찾는 데 그 수를 쓴다')
-  assert.ok(body.includes('JOURNAL_PRUNE_BUDGET_MS'), '한 창의 시간 상한을 본다')
-  assert.ok(/setImmediate/.test(body), '배치 사이에 루프를 비워 준다 — 없으면 나눈 뜻이 없다')
-  /* `DELETE … LIMIT` 은 드라이버마다 다르다 — 경계 `revision` 을 찾아 그 아래만 지운다. */
-  assert.ok(!/delete[\s\S]{0,200}limit\(/i.test(body), 'DELETE 에 LIMIT 을 붙이지 않는다')
-})
-
-/*
- * ★ 앞부분이 지워진 것을 목록이 말한다.
- *
- * 정리가 오래된 사건을 지우면 목록을 아무리 내려가도 어느 지점에서 기록이 끝난다. 화면이 그것을 말하지
- * 않으면 사람은 「이 트윈은 그때 시작했다」로 읽는다. 없었던 것과 지워진 것은 다른 사실이다.
- */
-test('★ 남아 있는 가장 오래된 리비전을 목록이 함께 낸다 — 지워진 것을 없었던 것으로 보이지 않게', () => {
-  const type = readFileSync(
-    join(import.meta.dirname, '..', 'server', 'service', 'twin-event', 'twin-event-type.ts'),
-    'utf8'
-  )
-  assert.match(type, /oldestRevision\?: number/, '목록 응답에 그 칸이 있어야 한다')
-  assert.match(type, /retention policy/, '무슨 뜻인지 설명이 있어야 한다(화면이 문구를 만든다)')
-
-  const query = readFileSync(
-    join(import.meta.dirname, '..', 'server', 'service', 'twin-journal', 'twin-journal-query.ts'),
-    'utf8'
-  )
-  /* 저장하지 않고 조회할 때 구한다 — 저장한 값은 실제 데이터와 어긋날 수 있다. */
-  assert.match(query, /orderBy\('e\.revision', 'ASC'\)[\s\S]{0,120}?limit\(1\)/, '가장 작은 리비전 한 행만 읽는다')
-  /* 트윈 하나를 물었을 때만 — 여러 트윈을 합치면 리비전은 트윈마다 따로 세는 번호다. */
-  assert.match(query, /if \(instanceIds\.length === 1\)/, '트윈 하나일 때만 낸다')
-  assert.match(query, /nextCursor, oldestRevision \}/, '응답에 실어 보낸다')
-})
-
-/*
- * ★ 경계를 시각순으로 찾는다 — 그러지 않으면 색인이 쓰이지 않는다.
- *
- * ── 무엇이 났나 (2026-08-27 실측 · 개발 파일 54GB · 3,128만 행) ───────────────
- * 배치 경계를 `ORDER BY revision` 으로 찾았다. 그러면 계획기가 리비전 색인을 고르고, 지울 대상인지는
- * 행마다 `created_at` 을 열어 확인한다. 지울 것이 적으면 그 트윈의 저널을 끝까지 걸어야 「한 배치를
- * 못 채웠다」를 알 수 있다 — 1,029만 행에서 그것이 2초 예산을 다 썼고 44건만 지우고 멈췄다.
- *
- * 실측한 질의 계획.
- *
- *   ORDER BY revision      SEARCH USING INDEX ix_twin_event_0             ← 행마다 테이블을 연다
- *   ORDER BY createdAt     SEARCH USING COVERING INDEX ix_twin_event_8    ← 테이블을 열지 않는다
- *   DELETE (정렬 없음)      SEARCH USING INDEX ix_twin_event_8            ← 색인만으로 이미 고쳐졌다
- *
- * 그리고 `created_at` 축 색인을 얹었다(`ix_twin_event_8`). 7일 밖 건수 조회가 208초에서 1.68초가 됐다.
- */
-test('★ 배치 경계를 createdAt 순으로 찾는다 — revision 순으로 찾으면 색인을 못 쓴다', () => {
-  const body = pruneBody()
-  assert.match(body, /\.orderBy\('e\.createdAt', 'ASC'\)/, '시각순으로 물어야 색인을 쓴다')
-  assert.doesNotMatch(body, /\.orderBy\('e\.revision', 'ASC'\)/, '리비전 순으로 되돌아가지 않는다')
-  /* 같은 시각의 행이 여럿일 수 있으므로 경계는 `<=` 다 — `<` 로 두면 제자리걸음이 된다. */
-  assert.match(body, /created_at <= :batchCutoff/, '경계 시각 이하까지 지운다')
-})
-
-test('★ createdAt 축 색인이 선언돼 있다 — 없으면 정리가 전량 주사한다', () => {
-  const entity = readFileSync(
-    join(import.meta.dirname, '..', 'server', 'service', 'twin-event', 'twin-event.ts'),
-    'utf8'
-  )
-  assert.match(
-    entity,
-    /@Index\('ix_twin_event_8', \(e: TwinEvent\) => \[e\.domain, e\.instanceId, e\.createdAt\]/,
-    '(domain, instanceId, createdAt) 색인이 있어야 한다'
-  )
-  /* 그리고 그것을 만드는 마이그레이션이 배선돼 있어야 한다 — 선언만 있으면 배포에 생기지 않는다. */
-  const list = readFileSync(join(import.meta.dirname, '..', 'server', 'migrations', 'index.ts'), 'utf8')
-  assert.match(list, /IndexEventCreatedAt1786400000000/, '마이그레이션 목록에 있어야 한다')
-})
-
-test('★ 한 문장이 짧아야 화면이 오래 멈추지 않는다 — 실측이 그 수를 정한다', () => {
-  /*
-   * ── 무엇이 났나 (2026-08-28 실측) ──────────────────────────────────────────
-   * 배치가 20,000 이었고, 한 문장이 그만큼 지우는 데 4~5.6초였다(서버 기록: hatio-mx2 20,130줄
-   * 5.2초). sqlite 는 연결이 하나라 그동안 **화면의 모든 질의가 줄을 선다** — 첫 화면 조회가
-   * 12.2초였다(정상 상태 40밀리초).
-   *
-   * 그리고 예산이 **문장이 끝난 뒤에** 검사되므로 한 문장이 2초 예산을 2~3배 넘겼다. 배치를 나눈 뜻이
-   * 그만큼 없어진다.
-   *
-   * 고칠 축은 총 시간이 아니라 **한 번에 멈추는 길이**다. 그래서 배치를 줄이고 예산을 늘렸다 —
-   * 지우는 양은 같고 잠금만 잘게 나뉜다.
-   */
-  const src = readFileSync(ENGINE, 'utf8')
-  const batch = /JOURNAL_PRUNE_BATCH\s*=\s*([0-9_]+)/.exec(src)?.[1]?.replace(/_/g, '')
-  const budget = /JOURNAL_PRUNE_BUDGET_MS\s*=\s*([0-9_]+)/.exec(src)?.[1]?.replace(/_/g, '')
-  assert.ok(batch && budget)
-  /* 줄당 약 0.26밀리초로 재었다 — 한 문장이 1초를 넘지 않아야 한다. */
-  const perStatementMs = Number(batch) * 0.26
-  assert.ok(perStatementMs <= 1000, `한 문장이 ${Math.round(perStatementMs)}밀리초로 추정된다 — 1초를 넘으면 화면이 그만큼 멈춘다`)
-  /* 예산이 문장 여럿을 담아야 나눈 뜻이 있다 — 하나만 담으면 예산 검사가 아무 일도 하지 않는다. */
-  assert.ok(Number(budget) / perStatementMs >= 3, '예산이 한 문장에 삼켜지면 배치를 나눈 뜻이 없다')
-  /* 실측 근거가 코드에 적혀 있어야 한다 — 다음 사람이 다시 재지 않고 바꾸지 않게. */
-  assert.match(src, /20,130줄/, '무엇을 재서 이 수가 나왔는지 적혀 있어야 한다')
-})

package/test/journal-sort-axis.test.ts

@@ -1,142 +0,0 @@
-/*
- * ★ 저널을 시간으로 거르면 **시간으로 정렬한다** — 축이 어긋나면 상한이 무력해진다.
- *
- * ── 무엇을 재서 알았나 (2026-08-22) ─────────────────────────────────────────
- * 서버가 간헐적으로 아주 느렸다. 원인은 저널 질의 둘이었고, 둘 다 같은 모양이었다: **거르는 축은
- * `eventTime`(시간창)이고 정렬 축은 `revision`.**
- *
- * 그러면 sqlite 는 조건에 맞는 행을 **전부 찾아 전부 정렬한 뒤** 상한을 적용한다. 상한이 정렬 **뒤에**
- * 걸리므로 아무것도 줄여 주지 않는다. 실측(인스턴스 하나가 375만 행):
- *
- *   성과 폴드   ORDER BY revision            LIMIT 20000 → 32.2초 · LIMIT 5000 → 28.3초 · 2000 → 28.2초
- *               ORDER BY eventTime, revision LIMIT 20000 →  0.41초                              (78배)
- *   저널 목록   ORDER BY revision DESC              200건 → 33.4초
- *               ORDER BY eventTime DESC, revision   200건 →  0.007초                        (4,700배)
- *
- * **상한을 낮추는 것으로는 고쳐지지 않는다** — 위 숫자가 그것을 말한다. 축이 원인이다.
- *
- * 계획도 그렇게 말한다: 어긋나면 `USE TEMP B-TREE FOR ORDER BY`(전체 정렬), 맞으면
- * `... FOR LAST TERM OF ORDER BY` — 시각은 인덱스(`ix_twin_event_1`)에서 순서대로 나오고 동시각만
- * 임시 정렬한다. 즉 범위를 훑다가 상한에서 멈춘다.
- *
- * ── 이 가드가 지키는 것 ─────────────────────────────────────────────────────
- * 사람은 이 어긋남을 **눈으로 못 본다.** 두 줄이 멀리 떨어져 있고, 작은 저널에서는 밀리초라 시험도
- * 초록이다. 규모에서만 드러나고, 그때는 「서버가 느리다」로만 보인다.
- *
- * 그래서 **소스를 훑어** 잡는다: 저널을 시간으로 거르는 질의가 시간으로 정렬하지 않으면 붉어진다.
- * 어휘를 세지 않고 **짝**을 본다 — 한 질의 안에서 시간 조건과 정렬 축이 함께 있는지.
- */
-import { test } from 'node:test'
-import assert from 'node:assert/strict'
-import { readFileSync, readdirSync, statSync } from 'node:fs'
-import { join } from 'node:path'
-
-/** 저널을 시간으로 거르는 표현 — TypeORM 의 두 방식(객체 조건·쿼리빌더). */
-const TIME_FILTER = /\beventTime\s*[:=]\s*(Between|LessThan|LessThanOrEqual|MoreThan|MoreThanOrEqual)\(|['"`][^'"`]*\beventTime\b[^'"`]*(BETWEEN|<=|>=|<|>)/
-
-/** 정렬 축 — `order: { … }` 와 `orderBy('e.…')` 양쪽. */
-const ORDER_AXIS = /order(?:By)?\s*[:(]\s*[{'"`]?\s*(?:'?e\.)?(\w+)/g
-
-function walk(dir: string, out: string[] = []): string[] {
-  for (const name of readdirSync(dir)) {
-    if (name === 'node_modules' || name.startsWith('.')) continue
-    const full = join(dir, name)
-    if (statSync(full).isDirectory()) walk(full, out)
-    else if (name.endsWith('.ts') && !name.endsWith('.d.ts')) out.push(full)
-  }
-  return out
-}
-
-/** 한 질의로 보이는 덩어리 — 저널 저장소를 부른 뒤 그 문장이 끝날 때까지. */
-function journalQueries(src: string): string[] {
-  const out: string[] = []
-  const re = /(?:getRepository|getReadRepository)\(\s*TwinEvent\s*\)/g
-  let m: RegExpExecArray | null
-  while ((m = re.exec(src))) {
-    /* 그 호출부터 다음 빈 줄까지를 한 질의로 본다 — 이 저장소의 질의는 그 안에서 끝난다. */
-    const rest = src.slice(m.index)
-    const end = rest.search(/\n\s*\n/)
-    out.push(rest.slice(0, end === -1 ? 1200 : Math.min(end, 1200)))
-  }
-  return out
-}
-
-test('저널을 시간으로 거르는 질의는 시간으로 정렬한다 — 상한이 살아 있게', () => {
-  const offenders: string[] = []
-
-  for (const file of walk(join(import.meta.dirname, '..', 'server'))) {
-    const src = readFileSync(file, 'utf8')
-    if (!src.includes('TwinEvent')) continue
-
-    for (const q of journalQueries(src)) {
-      if (!TIME_FILTER.test(q)) continue
-
-      /*
-       * **상한이 있는 질의만 본다.** 이 결함은 「상한이 정렬 뒤에 걸려 무력해지는 것」이다. 상한이 없는
-       * 질의(재개 시 체크포인트 뒤를 전부 계산하는 경로)는 어차피 전부 읽어야 하므로 정렬 축을 바꿔도
-       * 얻는 것이 없다 — 그 자리를 붉히면 **거짓 빨강**이고, 그런 가드는 없는 것보다 나쁘다.
-       */
-      if (!/\b(take|limit)\s*[:(]/.test(q)) continue
-
-      const axes: string[] = []
-      let a: RegExpExecArray | null
-      const re = new RegExp(ORDER_AXIS.source, 'g')
-      while ((a = re.exec(q))) axes.push(a[1])
-      if (!axes.length) continue /* 정렬이 없으면 이 결함이 아니다 */
-
-      /* 첫 정렬 축이 시간이어야 한다 — 뒤에 `revision` 이 오는 것은 동시각 가름이라 정상이다. */
-      if (axes[0] !== 'eventTime') {
-        offenders.push(`${file.replace(/^.*\/server\//, 'server/')} — 시간으로 거르면서 '${axes[0]}' 로 정렬`)
-      }
-    }
-  }
-
-  assert.deepEqual(
-    offenders,
-    [],
-    '시간창으로 거르면서 다른 축으로 정렬하면 sqlite 가 전량 정렬한 뒤 상한을 적용한다 ' +
-      '(실측 32.2초 대 0.41초). 정렬을 `eventTime` 먼저로 두고 동시각 가름을 위해 `revision` 을 뒤에 두라.\n' +
-      offenders.join('\n')
-  )
-})
-
-test('가드가 실제로 잡는다 — 거짓 초록을 내지 않는지 확인한다', () => {
-  /*
-   * 가드는 스스로를 증명해야 한다. 이 저장소에서 실제로 고친 두 모양을 그대로 넣어 **잡히는지** 본다.
-   * 잡지 못하는 가드는 없는 것보다 나쁘다(있다는 사실이 안심을 준다).
-   */
-  const bad = `
-    const rows = await getReadRepository(TwinEvent)
-      .createQueryBuilder('e')
-      .andWhere('e.eventTime BETWEEN :from AND :to', { from, to })
-      .orderBy('e.revision', 'ASC')
-      .limit(MAX_EVENTS)
-  `
-  const good = `
-    const rows = await getReadRepository(TwinEvent)
-      .createQueryBuilder('e')
-      .andWhere('e.eventTime BETWEEN :from AND :to', { from, to })
-      .orderBy('e.eventTime', 'ASC')
-      .addOrderBy('e.revision', 'ASC')
-      .limit(MAX_EVENTS)
-  `
-  const firstAxis = (q: string): string | undefined => {
-    const re = new RegExp(ORDER_AXIS.source, 'g')
-    const m = re.exec(q)
-    return m?.[1]
-  }
-
-  /* 상한이 없는 질의는 이 결함이 아니다 — 가드가 그것을 지나쳐야 한다. */
-  const noLimit = `
-    const rows = await getRepository(TwinEvent).find({
-      where: { ...baseWhere, eventTime: LessThanOrEqual(new Date(cutoffMs)) },
-      order: { revision: 'ASC' }
-    })
-  `
-  assert.equal(/\b(take|limit)\s*[:(]/.test(noLimit), false, '상한이 없는 질의를 알아본다(지나쳐야 한다)')
-  assert.equal(/\b(take|limit)\s*[:(]/.test(bad), true, '상한이 있는 질의를 알아본다')
-
-  assert.equal(TIME_FILTER.test(bad), true, '시간 조건을 알아본다')
-  assert.equal(firstAxis(bad), 'revision', '어긋난 정렬을 알아본다')
-  assert.equal(firstAxis(good), 'eventTime', '맞는 정렬을 알아본다')
-})