@things-factory/headless-twin 10.0.15 → 10.0.18

package/test/ingest-idempotent.test.ts

@@ -0,0 +1,132 @@
+/*
+ * ★ 같은 사실을 두 번 받으면 한 번만 반영한다.
+ *
+ * ── 왜 이것이 핵심인가 (2026-08-26 · 사용자) ─────────────────────────────────
+ * 「웹훅 이벤트이건 폴링 데이터이건 아이뎀포턴트를 유지할 수 있도록 로직을 세우는 것」이 핵심이다.
+ * 그것이 서면 가져오는 방식이 무엇이든 트윈이 안전하고, 커넥터마다 각자 조심하지 않아도 된다.
+ *
+ * ── 무엇이 났나 ─────────────────────────────────────────────────────────────
+ * 지금까지 중복은 커넥터마다 각자 막았다. 태양광 커넥터가 10초마다 물으면서 10분마다 바뀌는 값을 매번
+ * 다시 보냈고, 한 주기에 76건이 되풀이됐다(커넥터를 고쳐 2건이 됐다). 다음 커넥터가 잊으면 또 난다.
+ * 밀어 주는 방식으로 받으면 더 자주 난다 — 재전송이 정상이다.
+ *
+ * ── 정체를 무엇으로 보나 ────────────────────────────────────────────────────
+ * 봉투의 `eventId` 로는 판단할 수 없다. 보낸 쪽이 매번 새로 만드는 순번이고, 호출마다 1부터 다시
+ * 시작한다. 그래서 사실 자체로 판단한다 — 대상 · 사건 종류 · 연결된 시스템이 준 시각.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { factIdentity, FactDeduper } from '../server/engine/ingest-dedupe.js'
+
+const at = '2026-08-26T00:00:00.000Z'
+
+const energy = (equipmentId: string, kWh: number, when = at, eventId = 'x') => ({
+  eventId,
+  eventType: 'energy.generated',
+  eventTime: when,
+  tenantId: 't',
+  data: { equipmentId, kWh, at: when }
+})
+
+const status = (moverId: string, s: string, when = at) => ({
+  eventId: `s-${moverId}`,
+  eventType: 'equipment.status',
+  eventTime: when,
+  tenantId: 't',
+  data: { moverId, kind: 'pv-array', status: s, at: when }
+})
+
+test('★ 같은 사실이 두 번 오면 한 번만 지난다 — 보낸 쪽이 되풀이 보내도 트윈이 틀리지 않는다', () => {
+  const d = new FactDeduper()
+  const { fresh, duplicates } = d.filter([energy('inv-1', 574.8), energy('inv-1', 574.8)])
+  assert.equal(fresh.length, 1)
+  assert.equal(duplicates, 1)
+})
+
+test('★ 봉투의 순번이 달라도 같은 사실이면 한 번이다 — eventId 로는 판단할 수 없다', () => {
+  /* 같은 측정을 두 번 보내면 보낸 쪽이 새 순번을 붙인다. 그것으로 판단하면 중복을 못 잡는다. */
+  const d = new FactDeduper()
+  const { fresh, duplicates } = d.filter([energy('inv-1', 574.8, at, 't-energy-1'), energy('inv-1', 574.8, at, 't-energy-2')])
+  assert.equal(fresh.length, 1)
+  assert.equal(duplicates, 1)
+})
+
+test('★ 다른 사실은 지난다 — 대상이 다르면 다른 사실이다', () => {
+  const d = new FactDeduper()
+  const { fresh, duplicates } = d.filter([energy('inv-1', 574.8), energy('inv-2', 577.2)])
+  assert.equal(fresh.length, 2)
+  assert.equal(duplicates, 0)
+})
+
+test('★ 잰 시각이 나아가면 다른 사실이다 — 그것이 새 측정이다', () => {
+  const d = new FactDeduper()
+  const { fresh } = d.filter([energy('inv-1', 574.8, at), energy('inv-1', 580.1, '2026-08-26T00:10:00.000Z')])
+  assert.equal(fresh.length, 2)
+})
+
+test('★ 사건 종류가 다르면 다른 사실이다 — 같은 설비의 같은 시각이어도', () => {
+  const d = new FactDeduper()
+  const { fresh } = d.filter([energy('inv-1', 574.8), status('inv-1', 'busy')])
+  assert.equal(fresh.length, 2)
+})
+
+test('★ 정체를 알 수 없으면 거르지 않는다 — 모르는 것을 같다고 하면 다른 사실이 하나로 합쳐진다', () => {
+  const d = new FactDeduper()
+  const noTarget = { eventId: 'a', eventType: 'energy.demand.window', eventTime: at, tenantId: 't', data: { maxKW: 3 } }
+  const noTime = { eventId: 'b', eventType: 'equipment.status', tenantId: 't', data: { moverId: 'inv-9', status: 'idle' } }
+  assert.equal(factIdentity(noTarget), undefined)
+  assert.equal(factIdentity(noTime), undefined)
+  const { fresh, duplicates } = d.filter([noTarget, noTarget, noTime, noTime])
+  assert.equal(fresh.length, 4, '거르지 않고 통과시킨다')
+  assert.equal(duplicates, 0)
+})
+
+test('★ 늦게 도착한 옛 사실은 버리지 않는다 — 그것이 왔다는 것도 사실이다', () => {
+  /*
+   * 상태에 반영하지 않는 판단은 커널이 한다(시각 비교). 여기서 버리면 지난 기록에서 사라지고,
+   * 「늦게 왔다」는 사실 자체를 아무도 알 수 없게 된다.
+   */
+  const d = new FactDeduper()
+  const { fresh, duplicates } = d.filter([
+    energy('inv-1', 580.1, '2026-08-26T00:10:00.000Z'),
+    energy('inv-1', 574.8, at)
+  ])
+  assert.equal(fresh.length, 2)
+  assert.equal(duplicates, 0)
+})
+
+test('★ 창을 넘으면 잊는다 — 전부 기억할 수는 없다', () => {
+  const window = FactDeduper.WINDOW
+  try {
+    FactDeduper.WINDOW = 3
+    const d = new FactDeduper()
+    d.filter([energy('inv-1', 1, '2026-08-26T00:00:00.000Z')])
+    d.filter([
+      energy('inv-1', 2, '2026-08-26T00:01:00.000Z'),
+      energy('inv-1', 3, '2026-08-26T00:02:00.000Z'),
+      energy('inv-1', 4, '2026-08-26T00:03:00.000Z')
+    ])
+    /* 첫 사실은 창 밖으로 밀려났으므로 다시 오면 통과한다 — 그 사실을 시험으로 못 박는다. */
+    const { duplicates } = d.filter([energy('inv-1', 1, '2026-08-26T00:00:00.000Z')])
+    assert.equal(duplicates, 0)
+    assert.ok(d.size() <= 3)
+  } finally {
+    FactDeduper.WINDOW = window
+  }
+})
+
+test('버린 수를 함께 낸다 — 알리지 않고 버리지 않는다', () => {
+  const d = new FactDeduper()
+  const same = [energy('inv-1', 1), energy('inv-1', 1), energy('inv-1', 1), energy('inv-2', 2)]
+  const { fresh, duplicates } = d.filter(same)
+  assert.equal(fresh.length, 2)
+  assert.equal(duplicates, 2)
+})
+
+test('트윈마다 따로 센다 — 한 트윈의 되풀이가 다른 트윈을 막지 않는다', () => {
+  const a = new FactDeduper()
+  const b = new FactDeduper()
+  a.filter([energy('inv-1', 1)])
+  const { duplicates } = b.filter([energy('inv-1', 1)])
+  assert.equal(duplicates, 0)
+})

package/test/ingest-space.test.ts

@@ -1,5 +1,5 @@
 /*
- * 인제스트 공간 판정 — "이 현장에 더한다" 가 조용히 빗나가지 않게.
+ * 인제스트 공간 판정 — "이 현장에 더한다" 가 알리지 않고 빗나가지 않게.
  *
  * 엔진 본체는 DB·TypeORM 을 물고 있어 단위테스트로 부를 수 없다. 그래서 **결정만** 순수 모듈로
  * 떼어 놓고 여기서 본다(엔진은 공간 존재 여부를 조회해 넘기는 일만 한다).
@@ -26,7 +26,7 @@ test('마스터가 이미 그 공간이면 합치기가 아니다 — 같은 공
   assert.deepEqual(c, { spaceId: 'rosarito-site', joined: false })
 })
 
-test('없는 현장은 거절한다 — 조용히 새 공간을 만들지 않는다', () => {
+test('없는 현장은 거절한다 — 알리지 않고 새 공간을 만들지 않는다', () => {
   /* 여기서 새 공간을 만들어 주면 사용자는 합쳤다고 믿고 화면은 따로 논다. 그때는 이미 양쪽에
      이벤트가 쌓여 있어 손으로 합치는 것이 훨씬 비싸다. */
   assert.throws(
@@ -62,7 +62,7 @@ test('사이트 하나면 그 현장에 넣는다 — 렌즈를 더하는 정상
   assert.equal(refuseImportSpace(1, 'rosarito-site'), undefined)
 })
 
-test('사이트 여럿을 한 현장에 넣는 것은 거절한다 — 서로 다른 현장이 조용히 합쳐진다', () => {
+test('사이트 여럿을 한 현장에 넣는 것은 거절한다 — 서로 다른 현장이 알리지 않고 합쳐진다', () => {
   const r = refuseImportSpace(3, 'rosarito-site')
   assert.ok(r, '거절해야 한다')
   assert.equal(r.code, 'space-with-multiple-sites')

package/test/ingest-wiring-guard.test.ts

@@ -0,0 +1,197 @@
+/*
+ * 유입 배선 감시 — **커널이 문을 열었는데 그 문으로 가는 길이 없는 것**을 잡는다.
+ *
+ * ── 왜 있나 (2026-08-30) ────────────────────────────────────────────────────
+ * 2026-08-29 하루에 이 부류가 다섯 번 났다. 커널에 새 어휘의 문을 만들고, 정규 유입의 갈림에
+ * 그 길을 내지 않은 것이다. 그때마다 레코드는 **거부되지도 않고 아무 문에도 들어가지 못한 채**
+ * 사라졌다 — 커넥터는 보냈다고 믿고, 화면은 값이 없다고 말한다. 사람이 하나씩 찾아냈다.
+ *
+ * 다음 날 같은 부류의 **두 번째 얼굴**이 드러났다. EPCIS 갈래는 「나머지 전부」라, 새 어휘를 그
+ * 목록에서 빼 주지 않으면 레코드가 제 문으로 가면서 **EPCIS 문으로도 들어가 거부된다.** 받아들여
+ * 지기도 하고 거부되기도 하는 상태가 되어, 유입 장부의 거부 수가 늘고 사람이 그것을 진짜 결함으로
+ * 읽는다.
+ *
+ * ── 무엇을 지키나 ──────────────────────────────────────────────────────────
+ *   ① 커널의 유입 함수마다 부르는 곳이 있다
+ *   ② 어휘마다 **정확히 한 문**으로 간다 — 어느 문에도 못 가거나 두 문에 걸치지 않는다
+ *
+ * ── 목록을 손으로 적지 않는다 ──────────────────────────────────────────────
+ * 커널이 내보내는 이름에서 읽는다. 커널이 문을 늘리면 이 시험이 먼저 빨갛게 난다. 손 목록을 두면
+ * 늘어난 것을 모른다 — 이 저장소가 이미 그 실패를 겪었다(`vocabulary-labels` 의 주석).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+/* 유입 문과 판별 함수는 계약에 있다 — 커널은 엔진만 내보낸다(2026-08-30 층 분리). */
+import * as kernel from '@operato/ops-contract'
+import { ingestCanonicalRecords } from '../server/engine/canonical-ingest.ts'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const routerSource = readFileSync(join(here, '..', 'server', 'engine', 'canonical-ingest.ts'), 'utf-8')
+
+/**
+ * 정규 유입이 부르지 **않아도 되는** 것 — 각각 이유가 있다.
+ *
+ * 이 목록에 올릴 때는 이유를 함께 적는다. 이유 없이 올리면 이 시험은 아무것도 지키지 않는다.
+ */
+const NOT_ROUTED: Record<string, string> = {
+  /* 물류 어휘의 진입점 자체다 — 갈림이 이것을 부른다(이름이 `ingest` 하나뿐이라 규칙에 안 걸린다). */
+  ingest: 'EPCIS 어휘의 진입점. 갈림이 직접 부른다',
+  /* 마스터 데이터는 사건이 아니라 어휘 갱신이라 다른 경로로 간다. */
+  ingestMasterData: '사건이 아니라 어휘 갱신 — 참조 계층이 부른다'
+}
+
+test('★ 커널의 유입 함수마다 부르는 곳이 있다', () => {
+  const ingests = Object.keys(kernel).filter(n => /^ingest/.test(n))
+  assert.ok(ingests.length >= 8, `유입 함수를 못 읽었다(${ingests.length}개) — 커널을 다시 읽어야 한다`)
+
+  const unrouted = ingests.filter(n => !NOT_ROUTED[n] && !routerSource.includes(n))
+  assert.deepEqual(
+    unrouted,
+    [],
+    `커널이 문을 열었는데 정규 유입에 길이 없다:\n${unrouted.join('\n')}\n` +
+      '그 문으로 보내는 레코드는 거부되지도 않고 사라진다.\n' +
+      '갈림에 길을 내거나, 부르지 않아도 되는 이유를 NOT_ROUTED 에 적어라.'
+  )
+})
+
+test('부르지 않아도 되는 목록에 이유가 적혀 있다', () => {
+  for (const [name, why] of Object.entries(NOT_ROUTED)) {
+    assert.ok(why.trim().length > 5, `${name} 에 이유가 없다`)
+  }
+})
+
+/**
+ * 어휘마다 대표 레코드 하나 — **그 문으로만 가야 한다.**
+ *
+ * 값은 실제로 오는 모양에서 가져왔다(2026-08-29 실측). 지어낸 모양으로 검사하면 실제 레코드가
+ * 다른 문으로 가는 것을 놓친다.
+ */
+const NOW = '2026-08-30T00:00:00.000Z'
+const SAMPLES: { vocabulary: string; eventType: string; record: Record<string, unknown> }[] = [
+  {
+    vocabulary: '물품 관측(EPCIS)',
+    eventType: 'epcis.ObjectEvent',
+    record: {
+      epc: 'urn:epc:id:sgtin:0614141.107346.2017',
+      action: 'OBSERVE',
+      bizStep: 'urn:epcglobal:cbv:bizstep:storing',
+      readPoint: 'rack-1'
+    }
+  },
+  { vocabulary: '계량 표본', eventType: 'energy.measured', record: { meterId: 'incoming', kW: 100, at: NOW } },
+  {
+    vocabulary: '설비 상태',
+    eventType: 'energy.equipment',
+    record: { equipmentId: 'inv-1', generatedKW: 24.6, dcVoltage: 469.13, at: NOW }
+  },
+  { vocabulary: '발전 적산', eventType: 'energy.generated', record: { equipmentId: 'inv-1', kWh: 174, at: NOW } },
+  {
+    vocabulary: '마감된 사용 구간',
+    eventType: 'energy.usage.period',
+    record: {
+      meterId: 'incoming',
+      from: '2026-08-29T15:00:00.000Z',
+      to: '2026-08-29T16:00:00.000Z',
+      kWh: 474.48,
+      maxKW: 478.08,
+      unitPrice: 87.3,
+      currency: 'KRW',
+      basis: 'provider'
+    }
+  },
+  {
+    vocabulary: '요금 기준',
+    eventType: 'energy.tariff.basis',
+    record: {
+      /* 기준 선언은 **끝나지 않은 달**이 정상이다 — 사건 시각이 기간의 시작이라 미래에 적히지 않는다. */
+      from: '2026-07-31T15:00:00.000Z',
+      to: '2026-08-31T15:00:00.000Z',
+      billingDemandKW: 1650,
+      demandChargePerKW: 8320,
+      currency: 'KRW'
+    }
+  },
+  {
+    vocabulary: '청구서',
+    eventType: 'energy.bill',
+    record: {
+      /*
+       * 청구서는 **마감된 달**이다. 처음 이 표본은 끝나지 않은 8월을 담고 있었는데, 그것은 실제로
+       * 들어와 있던 잘못된 데이터를 그대로 베낀 것이었다(2026-08-30). 그 데이터 때문에 한 현장의
+       * 성과 구간이 미래로 밀려 화면이 비어 있었다. 표본이 결함을 베끼면 시험이 결함을 지킨다.
+       */
+      from: '2026-06-30T15:00:00.000Z',
+      to: '2026-07-31T15:00:00.000Z',
+      demandCharge: 13_728_000,
+      currency: 'KRW',
+      billingDemandKW: 1650
+    }
+  },
+  {
+    vocabulary: '발전 단가',
+    eventType: 'energy.generation.price',
+    record: { from: '2026-08-29T15:00:00.000Z', to: '2026-08-30T15:00:00.000Z', unitPrice: 148.61, currency: 'KRW' }
+  },
+  {
+    /*
+     * 라이브에서는 커널이 스스로 마감해 내지만, **지난 기록을 채울 때**는 밖에서 들어온다.
+     * 구간이 있으므로 적산의 문(`energy.generated`)이 아니라 이쪽으로 가야 한다 — 겹치면 지난
+     * 기록이 「지금 적산」으로도 읽혀 트윈의 시계가 과거로 끌린다.
+     */
+    vocabulary: '마감된 발전 기간',
+    eventType: 'energy.generation.period',
+    record: {
+      equipmentId: '001',
+      from: '2026-08-28T15:00:00.000Z',
+      to: '2026-08-29T15:00:00.000Z',
+      kWh: 394.3,
+      accumulation: 'daily'
+    }
+  }
+]
+
+test('★ 어휘마다 정확히 한 문으로 간다 — 사라지지도, 두 문에 걸치지도 않는다', () => {
+  const wrong: string[] = []
+  for (const s of SAMPLES) {
+    const r = ingestCanonicalRecords([s.record] as any, 't', NOW)
+    const accepted = (r.accepted as any[]).map(e => e.eventType)
+    if (r.rejected.length) {
+      wrong.push(`${s.vocabulary}: 거부됐다 — ${JSON.stringify(r.rejected[0]?.errors)}`)
+      continue
+    }
+    if (accepted.length !== 1) {
+      wrong.push(`${s.vocabulary}: 봉투가 ${accepted.length}개다(${accepted.join(', ')}) — 한 문으로만 가야 한다`)
+      continue
+    }
+    if (accepted[0] !== s.eventType) wrong.push(`${s.vocabulary}: ${s.eventType} 이어야 하는데 ${accepted[0]} 로 갔다`)
+  }
+  assert.deepEqual(wrong, [], `\n${wrong.join('\n')}`)
+})
+
+test('★ 한 배치에 모든 어휘가 섞여 와도 각자의 문으로 간다', () => {
+  const r = ingestCanonicalRecords(SAMPLES.map(s => s.record) as any, 't', NOW)
+  assert.deepEqual(r.rejected, [], `거부가 없어야 한다: ${JSON.stringify(r.rejected)}`)
+  assert.deepEqual(
+    (r.accepted as any[]).map(e => e.eventType).sort(),
+    SAMPLES.map(s => s.eventType).sort()
+  )
+})
+
+test('커널이 어휘를 늘리면 이 시험이 먼저 안다', () => {
+  /*
+   * 판별 함수의 수와 위 표본의 수가 어긋나면, 커널에 어휘가 늘었는데 여기 표본이 없다는 뜻이다.
+   * (EPCIS 안의 갈림 둘(담김·변환)은 한 어휘로 센다 — 같은 문으로 간다.)
+   */
+  const gates = Object.keys(kernel).filter(n => /^is.*Record$/.test(n))
+  const counted = gates.filter(n => !['isAggregationRecord', 'isTransformationRecord', 'isMasterDataRecord'].includes(n))
+  assert.equal(
+    counted.length,
+    SAMPLES.length,
+    `커널의 어휘는 ${counted.length}개인데 표본은 ${SAMPLES.length}개다:\n${counted.join(' ')}\n` +
+      '늘어난 어휘의 표본을 SAMPLES 에 더하라 — 그래야 그 어휘도 한 문으로 가는지 검사된다.'
+  )
+})

package/test/integration-probes.test.ts

@@ -2,7 +2,7 @@
  * ★ 연결 적합성 하네스 — **절반만 돌린 스위트가 초록을 주장하지 못하게.**
  *
  * 지키는 것:
- *  ① 돌리지 않은 프로브는 **「모른다」**로 접힌다 → 판정이 그 단계를 달성으로 만들지 않는다.
+ *  ① 돌리지 않은 프로브는 **「모른다」**로 처리된다 → 판정이 그 단계를 달성으로 만들지 않는다.
  *  ② **실패한 프로브의 수를 0 으로 읽지 않는다.** 「0건이었다」와 「세지 못했다」는 다른 사실이다.
  *  ③ **쓰기 프로브는 동의 없이 계획에 들어오지 않는다** — 남의 운영 시스템에 명령을 넣는 일이다.
  *  ④ **게이팅 실패 뒤는 돌리지 않는다** — 빨간 칸을 늘리는 것은 원인을 알려 주지 않는다.
@@ -29,7 +29,7 @@ test('시퀀스는 읽기부터 시작하고 쓰기 프로브는 하나뿐이다
   assert.deepEqual(PROBE_SEQUENCE.filter(p => p.writes).map(p => p.id), ['actuate-effect'])
 })
 
-test('아무것도 돌리지 않았으면 첫 칸부터 「모른다」다 — 실패로 접지 않는다', () => {
+test('아무것도 돌리지 않았으면 첫 칸부터 「모른다」다 — 실패로 계산하지 않는다', () => {
   const p = assessStagePath(foldProbeResults([]))
   assert.equal(p.reached, null)
   assert.deepEqual(p.next?.stage, 'structure')
@@ -64,7 +64,7 @@ test('측정하지 못한 프로브는 수를 들지 않는다 — 0 을 지어
   assert.deepEqual(assessStagePath(e).stages[1].unmeasured, ['removals'])
 })
 
-test('세어서 0 을 얻은 것은 사실이다 — 모른다로 접지 않는다', () => {
+test('세어서 0 을 얻은 것은 사실이다 — 모른다로 계산하지 않는다', () => {
   const rs: ProbeResult[] = [...readOnlyAllPass().filter(r => r.id !== 'live-removal'),
     { id: 'live-removal', ran: true, passed: false, count: 0 }]
   const e = foldProbeResults(rs)

package/test/integration-runner.test.ts

@@ -39,7 +39,7 @@ test('시뮬 트윈은 라이브가 해당 없음이고, 그 사유를 말한다
   const a = assessSuite({ ...live(), subject: 'sim', journalTotal: null, removalsJournaled: null })
   assert.deepEqual(a.notApplicable.map(n => n.id), ['live-ingest', 'live-removal'])
   assert.deepEqual(a.path.stages[1].blockedBy, ['subject-is-simulation'])
-  assert.deepEqual(a.path.stages[1].unmeasured, [], '해당 없음을 미측정으로 접지 않는다')
+  assert.deepEqual(a.path.stages[1].unmeasured, [], '해당 없음을 미측정으로 계산하지 않는다')
   assert.equal(a.path.reached, 'structure')
   assert.ok(!a.planned.includes('live-removal'), '해당 없는 프로브는 계획하지 않는다')
 })

package/test/item-ref.test.ts

@@ -1,7 +1,7 @@
 /*
  * 개체 → 품목 참조 — **정체성 모양이 하나가 아니고, 구분자는 우리가 정하지 않는다** (2026-08-23).
  *
- * ── 무엇이 조용히 비어 있었나 ───────────────────────────────────────────────
+ * ── 무엇이 알리지 않고 비어 있었나 ───────────────────────────────────────────────
  * 화면이 「이 개체는 선언된 자재가 아닙니다」라고 말했다. 그런데 그 품목은 원본의 선언에 이름까지 있었고
  * (「냉동그린빈스」), 대응 표도 멀쩡했다. 원인은 참조를 꺼내는 규칙이 GS1 SGTIN 하나만 알았던 것이다.
  *

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

@@ -0,0 +1,80 @@
+/*
+ * ★ 필터가 없을 때도 시각순으로 낸다 — 상한이 시간축의 임의 구간을 잘라내던 자리.
+ *
+ * ── 무엇이 났나 (2026-08-25 실측 · 승화푸드) ─────────────────────────────────
+ * 공정 타임라인은 필터 없이 상한만 걸고 지난 기록을 부른다.
+ *
+ *   loadTwinEvents(id, { eventType: 'task.status', limit: TASK_CAP })
+ *
+ * 그 갈래의 정렬이 `revision DESC` 였다. `revision` 은 **적힌 순서**다. 연결된 시스템을 되읽는
+ * 트윈에서는 적힌 순서와 일어난 순서가 다르다 — 커넥터가 연결된 시스템의 갱신 순서를 걷기 때문에,
+ * 그쪽에서 나중에 손댄 행이 4월 사실을 담고 있으면 그 행이 큰 revision 을 받는다.
+ *
+ *   작업 축에 있는 가장 늦은 사실      2026-08-23 03:20
+ *   revision 이 가장 큰 작업 사실      2026-04-15 10:49   ← 상한이 잡던 값
+ *
+ * 상한 안에 8월 두 달치가 들어오지 않았고, 화면은 4월 사실을 최근 것으로 그렸다. 사용자가 세 번
+ * 짚었다. 화면이 낸 「앞부분이 빠져 있습니다」도 사실과 달랐다 — 빠진 것은 앞부분이 아니라 시간축의
+ * 임의 구간이었다.
+ *
+ * ── 성능은 이유가 되지 않는다 ───────────────────────────────────────────────
+ * 오히려 시각 정렬이 인덱스(`ix_twin_event_1`)를 순서대로 타서 빠르다. 같은 파일의 실측 기록:
+ * `revision DESC` 200건 33.4초 · `eventTime DESC, revision DESC` 200건 0.007초.
+ *
+ * ── `revision` 순서를 없애지는 않는다 ───────────────────────────────────────────
+ * 부르는 쪽이 `revision` 범위로 물었으면 그 순서가 물음의 답이다. 거르는 축과 정렬 축을 맞추는
+ * 규칙과도 같다(`journal-sort-axis.test.ts`).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { journalOrder } from '../server/service/twin-journal/journal-order.js'
+
+test('★ 아무 필터도 없으면 시각순이다 — 타임라인이 부르는 방식이 이것이다', () => {
+  assert.deepEqual(journalOrder({}), { eventTime: 'DESC', revision: 'DESC' })
+  assert.deepEqual(journalOrder({ untilTime: null, fromRevision: null, toRevision: null }), {
+    eventTime: 'DESC',
+    revision: 'DESC'
+  })
+})
+
+test('★ 시각으로 물으면 시각순이다 — 거르는 축과 정렬 축이 맞아야 상한이 일한다', () => {
+  assert.deepEqual(journalOrder({ untilTime: '2026-08-25T00:00:00.000Z' }), { eventTime: 'DESC', revision: 'DESC' })
+})
+
+test('★ `revision` 범위로 물으면 그 순서로 낸다 — 그때는 그것이 물음의 답이다', () => {
+  assert.deepEqual(journalOrder({ fromRevision: 100, toRevision: 200 }), { revision: 'DESC' })
+  assert.deepEqual(journalOrder({ toRevision: 200 }), { revision: 'DESC' })
+  assert.deepEqual(journalOrder({ fromRevision: 100 }), { revision: 'DESC' })
+})
+
+test('시각과 `revision` 이 함께 오면 시각이 이긴다 — 거르는 쪽이 그렇게 정해져 있다', () => {
+  /*
+   * `where` 절이 `untilTime` 을 먼저 보고 `revision` 조건을 쓰지 않는다. 정렬만 `revision` 으로 두면 축이
+   * 어긋나고, 그 어긋남이 바로 위 실측의 33.4초다.
+   */
+  assert.deepEqual(journalOrder({ untilTime: '2026-08-25T00:00:00.000Z', fromRevision: 1, toRevision: 9 }), {
+    eventTime: 'DESC',
+    revision: 'DESC'
+  })
+})
+
+test('동시각의 순서는 `revision` 이 정한다 — 둘째 축을 없애지 않는다', () => {
+  /* 같은 시각에 여러 사실이 들어오는 것은 흔하다(한 번의 폴링이 여러 행을 낸다). 그때 순서가 없으면
+     화면이 새로 고칠 때마다 줄 순서가 바뀐다. */
+  for (const q of [{}, { untilTime: '2026-08-25T00:00:00.000Z' }]) {
+    assert.equal(journalOrder(q).revision, 'DESC')
+  }
+})
+
+test('구간으로 물으면 시각순이다 — 화면이 그리는 구간을 그대로 묻는 길', () => {
+  assert.deepEqual(journalOrder({ fromTime: '2026-08-22T00:00:00.000Z' }), { eventTime: 'DESC', revision: 'DESC' })
+  assert.deepEqual(
+    journalOrder({ fromTime: '2026-08-22T00:00:00.000Z', untilTime: '2026-08-23T00:00:00.000Z' }),
+    { eventTime: 'DESC', revision: 'DESC' }
+  )
+  /* 구간과 `revision` 범위가 함께 와도 시각이 이긴다 — 거르는 쪽이 그렇게 정해져 있다. */
+  assert.deepEqual(
+    journalOrder({ fromTime: '2026-08-22T00:00:00.000Z', fromRevision: 1, toRevision: 9 }),
+    { eventTime: 'DESC', revision: 'DESC' }
+  )
+})

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

@@ -12,7 +12,7 @@
  * ── 규율 ────────────────────────────────────────────────────────────────────
  * 저널(`TwinEvent`)을 `find()` 로 읽는 자리는 둘 중 하나여야 한다.
  *  ① **상한이 있다**(`take:`) — 목록·표본처럼 화면이 쓰는 만큼만 읽는 경우.
- *  ② **폴드다** — 사실을 하나씩 접는 것이 목적이라 그 구간의 행이 필요한 경우. 이때는 바로 앞에
+ *  ② **폴드다** — 사실을 하나씩 계산하는 것이 목적이라 그 구간의 행이 필요한 경우. 이때는 바로 앞에
  *     `journal-fold:` 로 시작하는 주석을 두어 **왜 필요한지**, 그리고 상한이 없다면 **없어질 조건**을
  *     함께 적는다.
  *
@@ -101,7 +101,7 @@ test('저널을 통째로 읽는 자리는 폴드라고 밝히고 이유를 적
     `이유 없이 저널 전체를 읽는 자리 ${bare.length}곳:\n  ${bare.join('\n  ')}\n\n` +
       `둘 중 하나로 만든다.\n` +
       `  ① 화면이 쓰는 만큼만 읽는다면 \`take:\` 를 준다.\n` +
-      `  ② 사실을 접는 것이 목적이라면 바로 앞에 \`journal-fold:\` 주석으로 왜 행이 필요한지,\n` +
+      `  ② 사실을 계산하는 것이 목적이라면 바로 앞에 \`journal-fold:\` 주석으로 왜 행이 필요한지,\n` +
       `     상한이 없다면 그 예외가 없어질 조건까지 적는다.\n\n` +
       `수 몇 개만 필요하다면 셋째 길이 맞다: 집계는 DB 가 한다(MIN/MAX/COUNT + createQueryBuilder).\n` +
       `\`timeRange\` 가 min/max 두 수를 구하려고 275,882행·payload 131MB 를 4초마다 파싱했던 자리다.`
@@ -111,10 +111,20 @@ test('저널을 통째로 읽는 자리는 폴드라고 밝히고 이유를 적
 test('검사가 실제로 저널 읽기를 보고 있다 — 대상이 사라지면 초록이 거짓이 된다', () => {
   const sites = journalFindSites()
 
+  /*
+   * ── 문턱을 셋에서 둘로 내렸다 (2026-08-28) ─────────────────────────────────
+   * 자리 하나를 **질의 빌더로 옮겨서** 줄었다(계보 조회 — 관계로 물어 두 단계 질의가 되고 `take` 가
+   * 있어도 안쪽에 상한이 없던 자리다). 그 방향이 이 검사가 바라는 방향이므로 문턱을 따라 내린다.
+   *
+   * 이 단정의 뜻은 「자리가 많아야 한다」가 아니라 **「검사가 무언가를 보고 있어야 한다」**다. 남은 둘도
+   * 옮겨지면 이 시험이 빨개지는데, 그때가 바로 사람이 알아야 하는 순간이다 — 검사가 아무것도 보지 않는
+   * 채로 초록이면 그 초록이 거짓이다. 그때는 검사의 패턴을 질의 빌더 쪽으로 옮긴다.
+   */
   assert.ok(
-    sites.length >= 3,
-    `저널 \`find()\` 를 ${sites.length}곳 찾았다 — 셋보다 적으면 호출 형태가 바뀐 것이다(리포지토리를 ` +
-      `변수에 담아 부르면 이 검사가 놓친다). 그때는 이 검사의 패턴을 함께 옮긴다.`
+    sites.length >= 2,
+    `저널 \`find()\` 를 ${sites.length}곳 찾았다 — 둘보다 적으면 이 검사가 보는 대상이 없어졌다는 뜻이다. ` +
+      `호출을 질의 빌더로 옮겼다면 이 검사의 패턴도 그쪽으로 옮긴다(리포지토리를 변수에 담아 부르는 ` +
+      `형태도 함께 본다).`
   )
 })
 
@@ -173,5 +183,5 @@ test('건수 상한이 값으로 선언돼 있고, 넘으면 전체를 비운다
   assert.match(src, /take\(COUNT_CAP \+ 1\)/, '상한을 넘었는지 알려면 하나 더 읽어야 한다')
   /* 상한을 넘으면 **전체를 비운다** — 상한값을 전체로 적으면 화면이 거짓을 말한다. */
   assert.match(src, /capped \? undefined : counted\.length/)
-  assert.match(src, /capped/, '넘었다는 사실을 함께 낸다(조용히 자르지 않는다)')
+  assert.match(src, /capped/, '넘었다는 사실을 함께 낸다(알리지 않고 자르지 않는다)')
 })