@things-factory/headless-twin 10.0.11 → 10.0.13

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

@@ -86,7 +86,7 @@ before(async () => {
   const d = await ds.getRepository(Domain).save({ name: 'guard-test', subdomain: 'guard-test' } as any)
   domainId = d.id
 
-  await TwinEngine.ingestMaster(domainId, master(3, '서울 창고', '보관 구역'))
+  await TwinEngine.ingestMaster(domainId, master(3, '서울 창고', '보관 구역'), 'reset')
 })
 
 after(async () => {
@@ -95,7 +95,7 @@ after(async () => {
 })
 
 test('멈춰 있으면 재인제스트가 통한다 — 막는 것은 가동 중일 때뿐이다', async () => {
-  await TwinEngine.ingestMaster(domainId, master(5, '서울 창고', '보관 구역'))
+  await TwinEngine.ingestMaster(domainId, master(5, '서울 창고', '보관 구역'), 'reset')
   const t = await trace()
   assert.equal(t.boardLocations, 6, '자리 6개(도크 1 + 빈 5)로 갱신된다')
   assert.deepEqual(t.revs, [1, 2], '구조가 달라졌으니 리비전이 하나 늘어난다')
@@ -103,7 +103,7 @@ test('멈춰 있으면 재인제스트가 통한다 — 막는 것은 가동 중
 })
 
 test('가동 중이면 거절하고 — **아무것도 바꾸지 않는다**', async () => {
-  await TwinEngine.startFromRegistry(domainId, INSTANCE, 'sim-experiment')
+  await TwinEngine.startFromRegistry(domainId, INSTANCE, 'reset')
   const before = await trace()
 
   /*
@@ -111,7 +111,7 @@ test('가동 중이면 거절하고 — **아무것도 바꾸지 않는다**', a
    * 부분 쓰기는 앞쪽(공간·구역)에서 일어났으므로, 구조만 확인하면 예전 결함을 못 잡는다.
    */
   await assert.rejects(
-    () => TwinEngine.ingestMaster(domainId, master(9, '부산 창고', '다른 구역')),
+    () => TwinEngine.ingestMaster(domainId, master(9, '부산 창고', '다른 구역'), 'reset'),
     /is running/,
     '가동 중에는 거절해야 한다'
   )
@@ -121,7 +121,7 @@ test('가동 중이면 거절하고 — **아무것도 바꾸지 않는다**', a
 
 test('멈추면 다시 통한다 — 거절은 잠금이 아니라 순서다', async () => {
   await TwinEngine.stop(domainId, INSTANCE)
-  await TwinEngine.ingestMaster(domainId, master(9, '부산 창고', '다른 구역'))
+  await TwinEngine.ingestMaster(domainId, master(9, '부산 창고', '다른 구역'), 'reset')
 
   const t = await trace()
   assert.equal(t.boardLocations, 10, '아까 거절당한 그 구조가 이제 들어간다')

package/test/instance-cache-lifecycle.test.ts

@@ -74,7 +74,7 @@ after(async () => {
 })
 
 test('지운 트윈의 캐시는 남지 않는다 — TTL 은 없어진 주인을 지우지 않는다', async () => {
-  await TwinEngine.ingestMaster(domainId, master())
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
   /* 캐시를 실제로 채운다 — 손으로 넣으면 "채우는 경로" 가 바뀌어도 검사가 통과한다. */
   await TwinEngine.structureRevOf(domainId, INSTANCE)
   const { measured, structureRev } = caches()

package/test/integration-probes.test.ts

@@ -0,0 +1,103 @@
+/*
+ * ★ 연결 적합성 하네스 — **절반만 돌린 스위트가 초록을 주장하지 못하게.**
+ *
+ * 지키는 것:
+ *  ① 돌리지 않은 프로브는 **「모른다」**로 접힌다 → 판정이 그 단계를 달성으로 만들지 않는다.
+ *  ② **실패한 프로브의 수를 0 으로 읽지 않는다.** 「0건이었다」와 「세지 못했다」는 다른 사실이다.
+ *  ③ **쓰기 프로브는 동의 없이 계획에 들어오지 않는다** — 남의 운영 시스템에 명령을 넣는 일이다.
+ *  ④ **게이팅 실패 뒤는 돌리지 않는다** — 빨간 칸을 늘리는 것은 원인을 알려 주지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { PROBE_SEQUENCE, foldProbeResults, plannedProbes, type ProbeResult } from '../server/engine/integration-probes.ts'
+import { assessStagePath, forbiddenClaims } from '../server/engine/stage-path.ts'
+
+const pass = (id: any, count?: number, coverage?: { declared: number; total: number }): ProbeResult =>
+  ({ id, ran: true, passed: true, ...(count !== undefined ? { count } : {}), ...(coverage ? { coverage } : {}) })
+
+/** 읽기 프로브 전부 통과 — 반출까지 관측된 상태. */
+const readOnlyAllPass = (): ProbeResult[] => [
+  pass('connect'), pass('discover', 1), pass('master', 12), pass('master-warnings', 3), pass('items', 340),
+  pass('live-ingest', 1200), pass('live-removal', 17),
+  pass('declarations', undefined, { declared: 6, total: 8 }), pass('forecast'),
+  pass('actuate-declared')
+]
+
+test('시퀀스는 읽기부터 시작하고 쓰기 프로브는 하나뿐이다', () => {
+  assert.equal(PROBE_SEQUENCE[0].id, 'connect')
+  assert.deepEqual(PROBE_SEQUENCE.filter(p => p.writes).map(p => p.id), ['actuate-effect'])
+})
+
+test('아무것도 돌리지 않았으면 첫 칸부터 「모른다」다 — 실패로 접지 않는다', () => {
+  const p = assessStagePath(foldProbeResults([]))
+  assert.equal(p.reached, null)
+  assert.deepEqual(p.next?.stage, 'structure')
+  assert.ok(p.stages[0].blockedBy.includes('no-locations'))
+  assert.ok(p.stages[0].unmeasured.includes('master-warnings'), '세지 않은 것은 모르는 것이다')
+})
+
+test('읽기만 전부 통과하면 예측까지 도달하고 폐루프는 「검증되지 않음」으로 남는다', () => {
+  const p = assessStagePath(foldProbeResults(readOnlyAllPass()))
+  assert.equal(p.reached, 'forecast')
+  assert.deepEqual(p.stages[3].unmeasured, ['correlated-effect'])
+  assert.deepEqual(p.stages[3].blockedBy, [], '능력은 선언∩구현이므로 막힌 것이 아니라 안 돌린 것이다')
+  assert.deepEqual(forbiddenClaims(p), ['claim.automatic-control'])
+})
+
+test('쓰기 프로브를 돌려 효과가 관측되면 폐루프가 닫힌다', () => {
+  const p = assessStagePath(foldProbeResults([...readOnlyAllPass(), pass('actuate-effect', 2)]))
+  assert.equal(p.reached, 'closed-loop')
+  assert.deepEqual(forbiddenClaims(p), [])
+})
+
+test('측정하지 못한 프로브는 수를 들지 않는다 — 0 을 지어내지 않는다', () => {
+  /*
+   * 규칙은 「실패면 모른다」가 아니다 — **센 값은 판정과 무관한 사실**이다(0건도 사실이다).
+   * 측정 자체를 못 한 프로브(타임아웃 등)는 `count` 를 **비운다**. 0 을 채우면 「세어 보니 없었다」로
+   * 읽히고, 그건 스냅샷 피드를 delta 로 오인하게 만드는 정반대의 결론을 낳는다.
+   */
+  const rs: ProbeResult[] = [...readOnlyAllPass().filter(r => r.id !== 'live-removal'),
+    { id: 'live-removal', ran: true, passed: false, detail: 'timeout' }]
+  const e = foldProbeResults(rs)
+  assert.equal(e.removalsObserved, null, '측정하지 못했으면 모른다')
+  assert.deepEqual(assessStagePath(e).stages[1].unmeasured, ['removals'])
+})
+
+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)
+  assert.equal(e.removalsObserved, 0)
+  assert.deepEqual(assessStagePath(e).stages[1].blockedBy, ['no-removal-observed'])
+})
+
+test('반출을 세었는데 0 이면 라이브가 막힌다 — 스냅샷 되풀어 읽기', () => {
+  const rs: ProbeResult[] = [...readOnlyAllPass().filter(r => r.id !== 'live-removal'), pass('live-removal', 0)]
+  const p = assessStagePath(foldProbeResults(rs))
+  assert.deepEqual(p.stages[1].blockedBy, ['no-removal-observed'])
+  assert.equal(p.reached, 'structure')
+  assert.ok(forbiddenClaims(p).includes('claim.realtime'))
+})
+
+test('쓰기 프로브는 동의 없이 계획에 들어오지 않는다', () => {
+  assert.ok(!plannedProbes([]).includes('actuate-effect'))
+  assert.ok(plannedProbes([], { allowWrites: true }).includes('actuate-effect'))
+})
+
+test('게이팅 프로브가 실패하면 그 뒤는 계획하지 않는다', () => {
+  const planned = plannedProbes([{ id: 'connect', ran: true, passed: false, detail: '401' }])
+  assert.deepEqual(planned, [], '붙지 못했으면 뒤를 두드릴 이유가 없다')
+})
+
+test('통과한 프로브는 다시 계획하지 않고, 남은 것만 계획한다', () => {
+  const planned = plannedProbes([pass('connect'), pass('discover', 1)])
+  assert.equal(planned[0], 'master')
+  assert.ok(!planned.includes('connect'))
+})
+
+test('게이팅이 아닌 프로브의 실패는 뒤를 멈추지 않는다', () => {
+  const planned = plannedProbes([pass('connect'), pass('discover', 1), pass('master', 12),
+    { id: 'master-warnings', ran: true, passed: false, detail: 'not-counted' }])
+  assert.ok(planned.includes('items'), '못 옮긴 값을 세지 못한 것이 구조 확인을 멈추지는 않는다')
+})

package/test/integration-runner.test.ts

@@ -0,0 +1,95 @@
+/*
+ * ★ 실행기 — **회색 칸이 빨간 칸으로 위장되지 않게.**
+ *
+ *  ① 시뮬 트윈에 라이브를 요구하지 않는다(해당 없음). 그 빨강은 결함이 아니다.
+ *  ② 템플릿으로 세운 트윈에는 옮겨 온 마스터가 없다 — 「못 옮긴 값」을 물을 대상이 아니다.
+ *  ③ 반출 0 의 처방이 둘로 갈린다: 스냅샷이면 방식을 바꿔야 하고, 아니면 더 기다릴 수 있다.
+ *  ④ 액추에이션은 계약에 없다 — 측정을 만들지 않고 미실행으로 남긴다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { assessSuite, type SuiteFacts } from '../server/engine/integration-runner.ts'
+
+const live = (): SuiteFacts => ({
+  subject: 'live',
+  fromReference: true,
+  adapterCapabilities: ['live'],
+  connectOk: true,
+  siteCount: 3,
+  locationCount: 12,
+  itemCount: 340,
+  lastWarningCount: 2,
+  journalTotal: 1200,
+  removalsJournaled: 17,
+  specCoverage: { declared: 6, total: 8 },
+  forecastRan: true,
+  feed: 'delta-poll'
+})
+
+test('라이브 전부 갖추면 예측까지 도달하고, 폐루프는 능력이 없어 막힌다', () => {
+  const a = assessSuite(live())
+  assert.equal(a.path.reached, 'forecast')
+  assert.deepEqual(a.path.stages[3].blockedBy, ['no-actuate-capability'])
+  assert.deepEqual(a.forbiddenClaims, ['claim.automatic-control'])
+  assert.equal(a.profile.multiSite, true)
+})
+
+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.equal(a.path.reached, 'structure')
+  assert.ok(!a.planned.includes('live-removal'), '해당 없는 프로브는 계획하지 않는다')
+})
+
+test('템플릿으로 세운 트윈은 못 옮긴 값을 물을 대상이 아니다', () => {
+  const a = assessSuite({ ...live(), fromReference: false, lastWarningCount: null })
+  assert.deepEqual(a.notApplicable.map(n => n.id), ['master-warnings'])
+  assert.equal(a.path.stages[0].achieved, true, '해당 없음이 구조 달성을 막지 않는다')
+})
+
+test('반출 0 — 스냅샷이면 방식을 바꿔야 한다고 말한다', () => {
+  const a = assessSuite({ ...live(), removalsJournaled: 0, feed: 'snapshot-poll' })
+  assert.deepEqual(a.path.stages[1].blockedBy, ['snapshot-only-feed'])
+  assert.ok(a.forbiddenClaims.includes('claim.realtime'))
+})
+
+test('반출 0 — 스냅샷이 아니면 아직 일어나지 않은 것일 수 있다', () => {
+  const a = assessSuite({ ...live(), removalsJournaled: 0, feed: 'delta-poll' })
+  assert.deepEqual(a.path.stages[1].blockedBy, ['no-removal-observed'])
+})
+
+test('승격 전 저널은 반출을 셀 수 없다 — 「없다」가 아니라 「모른다」', () => {
+  const a = assessSuite({ ...live(), removalsJournaled: null })
+  assert.deepEqual(a.path.stages[1].unmeasured, ['removals'])
+  assert.deepEqual(a.path.stages[1].blockedBy, [])
+})
+
+test('액추에이션 효과는 측정을 만들지 않고 미실행으로 남긴다', () => {
+  const a = assessSuite({ ...live(), adapterCapabilities: ['live', 'actuate'] })
+  const eff = a.results.find(r => r.id === 'actuate-effect')!
+  assert.equal(eff.ran, false)
+  assert.equal(eff.detail, 'actuation-not-wired')
+  assert.deepEqual(a.path.stages[3].unmeasured, ['correlated-effect'])
+})
+
+test('쓰기 프로브는 동의 없이 계획에 들어오지 않는다', () => {
+  const able = { ...live(), adapterCapabilities: ['live', 'actuate'] }
+  assert.ok(!assessSuite(able).planned.includes('actuate-effect'))
+  assert.ok(assessSuite(able, { allowWrites: true }).planned.includes('actuate-effect'))
+})
+
+test('액추에이션 능력이 없으면 쓰기 동의가 있어도 계획하지 않는다 — 보낼 문이 없다', () => {
+  assert.ok(!assessSuite(live(), { allowWrites: true }).planned.includes('actuate-effect'))
+})
+
+test('접속을 안 돌렸으면 구조부터 미측정이 아니라 미실행으로 남고, 계획의 첫 칸이 된다', () => {
+  const a = assessSuite({ ...live(), connectOk: null })
+  assert.equal(a.planned[0], 'connect')
+})
+
+test('못 옮긴 값이 0 이어도 세었으므로 통과다', () => {
+  assert.equal(assessSuite({ ...live(), lastWarningCount: 0 }).path.stages[0].achieved, true)
+})

package/test/item-ref.test.ts

@@ -0,0 +1,78 @@
+/*
+ * 개체 → 품목 참조 — **정체성 모양이 하나가 아니고, 구분자는 우리가 정하지 않는다** (2026-08-23).
+ *
+ * ── 무엇이 조용히 비어 있었나 ───────────────────────────────────────────────
+ * 화면이 「이 개체는 선언된 자재가 아닙니다」라고 말했다. 그런데 그 품목은 원본의 선언에 이름까지 있었고
+ * (「냉동그린빈스」), 대응 표도 멀쩡했다. 원인은 참조를 꺼내는 규칙이 GS1 SGTIN 하나만 알았던 것이다.
+ *
+ * ── 그리고 고치는 방향을 한 번 더 고쳤다 ────────────────────────────────────
+ * 처음에는 「`@` 뒤는 개체다」를 규칙으로 넣었다. 그것은 **한 원본(chef)의 관행**이고, 커널 계약이 그
+ * 구분자를 정한 적이 없다 — 사용자가 「이 화면이 특정 레거시를 기준으로 해서는 안 된다」고 짚었다.
+ * 그래서 자르는 판단을 걷고, **그 트윈의 선언과 견주어** 답한다.
+ *
+ * 이 시험이 지키는 것:
+ *  ① SGTIN 은 표준이 정한 자리에서 품목 참조를 꺼낸다.
+ *  ② 그 밖의 모양은 **손대지 않는다**(구분자를 모른다).
+ *  ③ 선언과 견줄 때는 두 방향을 본다 — 관측이 선언을 확장한 경우, 화면이 짧게 줄인 경우.
+ *  ④ 후보가 둘 이상이면 **답하지 않는다**(모르는 것이 틀린 답보다 낫다).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { itemRefOf, resolveByDeclaration } from '../server/service/twin-model/item-ref.ts'
+
+test('GS1 SGTIN 은 품목 참조 숫자다 — 표준이 자리를 정해 두었다', () => {
+  assert.equal(itemRefOf('urn:epc:id:sgtin:0614141.077101.42'), '077101')
+  assert.equal(itemRefOf('urn:epc:idpat:sgtin:0614141.078101.*'), '078101')
+})
+
+test('그 밖의 정체성은 손대지 않는다 — 어느 부호가 개체인지 우리가 정하지 않는다', () => {
+  assert.equal(itemRefOf('https://x.net/class/product-M1@M2R0001'), 'https://x.net/class/product-M1@M2R0001')
+  assert.equal(itemRefOf('https://x.net/class/product-M1'), 'https://x.net/class/product-M1')
+  assert.equal(itemRefOf('  https://x.net/class/p-1  '), 'https://x.net/class/p-1', '앞뒤 공백만 다듬는다')
+})
+
+test('읽을 수 없는 값은 null 이다', () => {
+  assert.equal(itemRefOf(''), null)
+  assert.equal(itemRefOf('   '), null)
+  assert.equal(itemRefOf(null), null)
+  assert.equal(itemRefOf(undefined), null)
+  assert.equal(itemRefOf(42), null)
+})
+
+const DECLARED = new Map<string, string>([
+  ['https://x.net/class/product-M0000438', 'M0000438'],
+  ['https://x.net/class/product-B0000033', 'B0000033']
+])
+
+test('그대로 같으면 그것이다', () => {
+  assert.equal(resolveByDeclaration('https://x.net/class/product-M0000438', DECLARED), 'M0000438')
+})
+
+test('관측이 선언을 확장한 경우 — 개체는 자기 클래스로 시작한다(부호를 모른다)', () => {
+  for (const sep of ['@', '#', '/', ':', '']) {
+    assert.equal(
+      resolveByDeclaration(`https://x.net/class/product-M0000438${sep}M2R0001`, DECLARED),
+      'M0000438',
+      `구분자 「${sep}」 에서도 같은 답이어야 한다`
+    )
+  }
+})
+
+test('화면이 짧게 줄인 경우 — 선언이 그것으로 끝난다', () => {
+  assert.equal(resolveByDeclaration('net/class/product-B0000033', DECLARED), 'B0000033')
+  assert.equal(resolveByDeclaration('product-M0000438', DECLARED), 'M0000438')
+})
+
+test('후보가 둘 이상이면 답하지 않는다 — 남의 레시피와 견주지 않게', () => {
+  const ambiguous = new Map<string, string>([
+    ['https://a.net/class/product-1', 'A1'],
+    ['https://b.net/class/product-1', 'B1']
+  ])
+  assert.equal(resolveByDeclaration('class/product-1', ambiguous), undefined)
+})
+
+test('선언에 없으면 없는 것이다 — 비슷한 것을 이어 주지 않는다', () => {
+  assert.equal(resolveByDeclaration('https://x.net/class/product-ZZZ', DECLARED), undefined)
+  assert.equal(resolveByDeclaration(null, DECLARED), undefined)
+})

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

@@ -0,0 +1,177 @@
+/*
+ * ★ 저널을 통째로 읽는 자리는 **코드에 그 이유가 적혀 있어야 한다** — 소스 규율 검사.
+ *
+ * ── 왜 이 검사가 필요한가 (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'
+
+/** 훑는 곳 — 저널을 읽을 수 있는 층 둘. */
+const ROOTS = [
+  new URL('../server', import.meta.url).pathname,
+  new URL('../../operato-twin/server', import.meta.url).pathname
+]
+
+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()
+
+  assert.ok(
+    sites.length >= 3,
+    `저널 \`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

@@ -0,0 +1,133 @@
+/*
+ * ★ 저널 보존 — **지우는 것은 선언이 있을 때만, 체크포인트가 대신할 수 있는 만큼만.**
+ *
+ * ── 왜 필요한가 (2026-08-22 실측) ───────────────────────────────────────────
+ * 개발 저널이 시간당 **581,794행 · 0.85GB**(하루 20GB)로 자랐다. 데모 MES 트윈 셋이 전체의 **97%** 를
+ * 만들고 지우는 것이 없었다. 같은 날 고친 질의들은 「그 크기에서도 빠르게」였고 **크기 자체를 줄이는
+ * 것은 없었다** — 그러면 며칠마다 같은 자리로 돌아온다.
+ *
+ * ── 그런데 저널을 지우는 것은 사실을 잃는 일이다 ────────────────────────────
+ * 그래서 이 시험이 세 규율을 고정한다. 규율이 깨지면 잃는 것이 조용하다 — 지워진 저널은 「없었던 일」과
+ * 구별되지 않는다.
+ *
+ *  ① **선언이 없으면 아무것도 지우지 않는다.** 기본값은 없음이다.
+ *  ② **체크포인트가 없는 인스턴스는 건드리지 않는다.** 그때 저널은 **유일한** 복구 수단이다
+ *     (엔진 주석: 「만료 시 저널 replay 폴백」). 둘을 함께 잃으면 그 트윈의 상태는 되돌릴 수 없다.
+ *  ③ **체크포인트 리비전보다 뒤는 지우지 않는다.** 그 뒤는 스냅샷이 대신하지 못한다.
+ *
+ * 그리고 보존 기간은 **스냅샷 TTL 보다 짧을 수 없다** — 짧으면 스냅샷이 살아 있는데 그것이 가리키는
+ * 앞쪽 저널이 없는 구간이 생기고, 시간여행·계보가 그 구간에서 조용히 빈다.
+ *
+ * ── 이 시험이 무엇을 재는가 ─────────────────────────────────────────────────
+ * DB 를 띄우지 않는다. 이 규율은 **조건을 어떻게 세우나**에 있고, 그것은 순수하게 확인할 수 있다 —
+ * 소스에서 그 조건 넷이 함께 있는지, 그리고 계약의 기본값이 무엇인지 본다. 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()
+  assert.match(body, /loadSnapshot\(/, '스냅샷을 확인해야 한다')
+  assert.match(body, /if \(!upTo\)[\s\S]{0,200}?continue/, '스냅샷이 없으면 그 인스턴스를 건너뛴다')
+  /* 건너뛴 사실을 세고 말한다 — 조용히 넘기면 「보존이 도는데 왜 안 줄어드나」가 된다. */
+  assert.match(body, /skipped\.push/, '건너뛴 것을 센다')
+})
+
+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 보다 짧아질 수 없다 — 짧으면 앞쪽이 비는 구간이 생긴다', () => {
+  const body = pruneBody()
+  assert.match(body, /SNAPSHOT_TTL_S \/ 86400/, '스냅샷 TTL 을 하한으로 삼아야 한다')
+  assert.match(body, /Math\.max\(days, minDays\)/, '선언이 그보다 짧으면 올린다')
+  assert.match(body, /twinWarn\(/, '올렸다는 사실을 말한다(조용히 바꾸지 않는다)')
+})
+
+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 한다')
+})