@things-factory/headless-twin 10.0.14 → 10.0.17

package/test/ingest-health-engine.test.ts

@@ -5,7 +5,7 @@
  * 실제로 받는 판정은 그 앞에 한 층이 더 있다: **피드 사실을 어디서 얻는가**(`liveFeedStateOf` — 이 트윈이
  * 미러인가 시뮬인가, 지금 도는가) 그리고 **장부를 어느 트윈의 것으로 찾는가**(도메인+인스턴스 키).
  *
- * 그 층이 틀리면 순수 시험은 전부 초록인 채로 화면만 거짓말한다. 실제로 두 가지가 조용히 틀릴 수 있다:
+ * 그 층이 틀리면 순수 시험은 전부 초록인 채로 화면만 거짓말한다. 실제로 두 가지가 알리지 않고 틀릴 수 있다:
  *  ① 시뮬 트윈이 「연결 안 됨」으로 보인다 — 거짓 경보이고, 거짓 경보는 참 경보를 죽인다
  *  ② 남의 도메인 장부를 집는다 — 키를 도메인 없이 만들면 그렇게 된다
  *
@@ -206,7 +206,7 @@ test('멈춘 미러는 「해당 없음」이다 — 고치려고 멈춰 둔 트
 
 test('멈춘 트윈에 계속 들어오면 「버려지는 중」이라 말한다 — 실제로 겪은 거짓 안심', async () => {
   /*
-   * 겪은 모습: 트윈이 멈췄는데 피드는 살아 레코드를 나르고, 커널은 조용히 버렸다. 화면은 「해당 없음 ·
+   * 겪은 모습: 트윈이 멈췄는데 피드는 살아 레코드를 나르고, 커널은 알리지 않고 버렸다. 화면은 「해당 없음 ·
    * 150 통과 · 100%」였다. 여기서는 그 상황을 그대로 만들어 판정과 수치를 확인한다.
    */
   /* 사람이 트윈을 멈춘다 — 그런데 피드는 남는다. 그 조합이 사실을 잃게 만든다. */

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

@@ -4,7 +4,7 @@
  * ── 왜 기계가 지켜야 하나 ───────────────────────────────────────────────────
  * 피드를 여는 경로가 둘이다(커넥터 `openLiveFeed` · 시나리오 `twin-ingest` 태스크). 한쪽만 장부에
  * 적으면 그 경로로 먹이는 트윈이 **「한 번도 받지 않은 것」**으로 보인다. 그 판정은 `unknown` 이고,
- * `unknown` 은 화면에서 「정상」과 구별되지 않는다 — 즉 **조용히 틀린 답**이 된다.
+ * `unknown` 은 화면에서 「정상」과 구별되지 않는다 — 즉 **오류 없이 틀린 답**이 된다.
  *
  * 세 번째 경로가 생길 때 사람이 이 사실을 기억할 것이라고 믿지 않는다. 인제스트를 부르는 자리를
  * 소스에서 찾아 장부 기록이 함께 있는지 본다.
@@ -86,7 +86,7 @@ test('검사가 실제로 경로를 보고 있다 — 대상이 사라지면 초
 
 test('유입 경로는 커널이 실제로 받은 수를 견준다 — 버려진 것을 통과로 세지 않게', () => {
   /*
-   * 겪은 일: 트윈이 멈춘 뒤에도 피드는 레코드를 나르고 커널은 조용히 버렸는데, 장부는 그것을 「통과」로
+   * 겪은 일: 트윈이 멈춘 뒤에도 피드는 레코드를 나르고 커널은 알리지 않고 버렸는데, 장부는 그것을 「통과」로
    * 셌다. 화면은 멈춘 트윈 옆에 「150 통과 · 100%」라고 적었다 — 사실이 사라지는 동안 안심시킨 것이다.
    *
    * 고친 방법은 `ingestLive` 가 **넣은 수를 돌려주는** 것이다. 새 경로가 그 반환을 안 쓰고 0 을 넘기면
@@ -100,9 +100,11 @@ test('유입 경로는 커널이 실제로 받은 수를 견준다 — 버려진
     missing,
     [],
     `커널이 받은 수를 견주지 않는 유입 경로 ${missing.length}곳:\n  ${missing.join('\n  ')}\n\n` +
-      `TwinEngine.ingestLive(...) 의 반환(넣은 수)을 받아 accepted.length 와의 차이를 ` +
-      `recordIngestResult(..., nowMs, undelivered) 로 넘긴다. 그러지 않으면 트윈이 멈춘 사이 ` +
-      `버려진 레코드가 「통과」로 집계되어 화면이 100% 라고 말한다.`
+      `TwinEngine.ingestLive(...) 또는 ingestLiveResult(...) 의 반환(넣은 수)을 받아 accepted.length 와의 ` +
+      `차이를 undelivered 라는 이름으로 recordIngestResult(..., nowMs, undelivered) 에 넘긴다. ` +
+      `그러지 않으면 트윈이 멈춘 사이 버려진 레코드가 「통과」로 집계되어 화면이 100% 라고 말한다.\n\n` +
+      `이 검사는 **그 이름이 있는지**만 본다(소스를 글자로 본다). 이름을 적고 0 을 넘기면 통과한다 — ` +
+      `그 경우는 사람이 보는 수밖에 없다.`
   )
 })
 

package/test/ingest-health.test.ts

@@ -53,7 +53,7 @@ test('오래 끊긴 피드는 건강했던 옛 창으로 초록을 내지 않는
   assert.equal(
     syncVerdictOf({ feedState: 'attached', recent: healthy, lastAtMs: 0, nowMs: STALE_AFTER_MS }),
     'syncing',
-    '경계까지는 아직 조용하다고 하지 않는다'
+    '경계까지는 아직 들어온 것이 없다고 하지 않는다'
   )
 })
 
@@ -73,7 +73,7 @@ test('붙었지만 한 번도 받지 않은 것을 「유입 없음」이라 단
   )
 })
 
-test('시뮬 트윈은 오래 조용해도 「유입 없음」이 아니다', () => {
+test('시뮬 트윈은 오래 들어온 것이 없어도 「유입 없음」이 아니다', () => {
   assert.equal(
     syncVerdictOf({ feedState: 'not-applicable', recent: null, lastAtMs: -1, nowMs: STALE_AFTER_MS * 100 }),
     'not-applicable'
@@ -82,7 +82,7 @@ test('시뮬 트윈은 오래 조용해도 「유입 없음」이 아니다', ()
 
 test('들어오는데 트윈이 안 돌면 「버려지는 중」이다 — 「해당 없음」으로 안심시키지 않는다', () => {
   /*
-   * 실제로 겪었다: 트윈이 멈춘 뒤에도 피드는 남아 레코드를 나르고, 커널은 그것을 조용히 버렸다.
+   * 실제로 겪었다: 트윈이 멈춘 뒤에도 피드는 남아 레코드를 나르고, 커널은 그것을 알리지 않고 버렸다.
    * 그런데 화면은 「해당 없음 · 150 통과 · 100%」였다 — 사실이 사라지는 동안 화면이 안심시킨 것이다.
    *
    * 멈춘 트윈의 피드 사실은 `not-applicable` 이므로, 미전달을 **그보다 먼저** 봐야 이 상태가 드러난다.
@@ -141,7 +141,7 @@ test('채우는 중인 창을 「최근」이라 부르지 않는다', () => {
   recordIngest(l, 100, [], 0)
   recordIngest(l, 100, [], 1000)
 
-  /* 읽는 시각을 넘긴다 — 넘기지 않으면 벽시계와 견주어 「오래 조용함」으로 읽힌다(1970년 장부이므로). */
+  /* 읽는 시각을 넘긴다 — 넘기지 않으면 벽시계와 견주어 「오래 들어온 것이 없음」으로 읽힌다(1970년 장부이므로). */
   const v = ingestHealth(l, 'attached', undefined, 1000)
   assert.equal(v.recent, null, '창이 아직 닫히지 않았다')
   assert.equal(v.verdict, 'unknown', '그래서 판정도 모름이다')
@@ -167,7 +167,7 @@ test('추이 상한을 넘으면 오래된 창이 밀려나고, 밀려난 수를
 
   const v = ingestHealth(l, 'attached')
   assert.equal(v.trend.length, TREND_LIMIT)
-  assert.ok(v.trendDropped > 0, `밀려난 창을 조용히 버리지 않는다 — 실제 ${v.trendDropped}`)
+  assert.ok(v.trendDropped > 0, `밀려난 창을 알리지 않고 버리지 않는다 — 실제 ${v.trendDropped}`)
 })
 
 /* ── ③ 0 과 없음 ────────────────────────────────────────────────────────── */
@@ -213,7 +213,7 @@ test('사유 종류가 무한히 자라지 않는다 — 문구에 변수가 섞
   assert.equal(v.reasonsCapped, true, '접혔다는 사실을 말한다')
   assert.ok(
     v.reasons.some(r => r.reason === OTHER_REASON),
-    '접힌 것들이 갈 칸이 있다'
+    '모은 것들이 갈 칸이 있다'
   )
   assert.equal(v.total.rejected, REASON_LIMIT * 5, '건수는 하나도 잃지 않는다')
 })

package/test/ingest-history.test.ts

@@ -12,7 +12,7 @@
  *    거짓이 된다. 겹치면 메모리 쪽을 쓴다(같은 사실의 원본이다).
  * ② 어디서부터 메모리인지 밝힌다(`liveFrom`) — 화면이 근거를 말할 수 있게. 재기동 직후에는 `null`
  *    이고, 그때 보이는 것은 전부 표에서 온 것이다.
- * ③ **조용히 자르지 않는다** — 상한에서 밀려난 창 수와, 물은 기간이 잘렸다는 사실을 함께 낸다.
+ * ③ **알리지 않고 자르지 않는다** — 상한에서 밀려난 창 수와, 물은 기간이 잘렸다는 사실을 함께 낸다.
  * ④ 남의 도메인·남의 트윈의 창을 집지 않는다.
  * ⑤ 제시가 0 인 창의 통과율은 `null` 이다 — 빈 창은 완벽한 창이 아니다.
  */
@@ -157,7 +157,7 @@ test('기간 상한을 넘겨 물으면 자르고, 자른 사실을 낸다', asy
   const r = await ask(TWIN, HISTORY_HOURS_MAX + 100)
 
   assert.equal(r.hours, HISTORY_HOURS_MAX, '상한까지만 본다')
-  assert.equal(r.hoursClamped, HISTORY_HOURS_MAX + 100, '얼마를 물었는지 밝힌다 — 조용히 자르지 않는다')
+  assert.equal(r.hoursClamped, HISTORY_HOURS_MAX + 100, '얼마를 물었는지 밝힌다 — 알리지 않고 자르지 않는다')
 })
 
 test('상한 안에서는 잘렸다고 말하지 않는다 — 없는 문제를 만들지 않는다', async () => {

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/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/, '넘었다는 사실을 함께 낸다(알리지 않고 자르지 않는다)')
 })