@things-factory/headless-twin 10.0.14 → 10.0.17

package/test/merge-streams.test.ts

@@ -0,0 +1,70 @@
+/*
+ * ★ 나눠 묻고 합치는 규율 — 갈래마다 상한까지 받아야 합친 결과가 정확하다.
+ *
+ * ── 왜 이 시험이 있나 (2026-08-28) ──────────────────────────────────────────
+ * 「종류 IN + 시각순」은 색인을 못 쓴다. 그래서 종류를 하나씩 정확일치로 묻고 합치는데, 그때 함정이
+ * 하나 있다 — UX 레인이 구현 전에 짚어 주었다.
+ *
+ *   「갈래마다 상한을 걸면 합친 결과가 시각순으로 온전하지 않다.
+ *     종류 A 의 마지막이 종류 B 의 첫째보다 이를 수 있다.」
+ *
+ * 그 지적은 **갈래마다 상한보다 적게 받을 때** 참이다. 상한까지 받으면 성질이 선다: 어떤 갈래에서 빠진
+ * 행은 그 갈래의 상한 번째보다 뒤이고, 우리는 전체에서 상한 개만 취하므로 그 행이 이 페이지에 들어올 수
+ * 없다. 이 시험이 그 성질을 못박는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { mergeStreams } from '../server/service/twin-journal/event-type-split-shape.js'
+
+const byN = (a: { n: number }, b: { n: number }) => a.n - b.n
+const seq = (from: number, count: number) => Array.from({ length: count }, (_, i) => ({ n: from + i }))
+
+test('★ 한 갈래가 앞을 다 차지해도 전체에서 앞 limit 개가 나온다 — 짚어 준 그 경우다', () => {
+  /*
+   * A 가 1~5, B 가 100~104. limit 3 이면 답은 A 의 1,2,3 이다. B 는 한 건도 들어오지 않는 것이 맞다.
+   */
+  const r = mergeStreams([seq(1, 5), seq(100, 5)], 3, byN)
+  assert.deepEqual(r.items.map(x => x.n), [1, 2, 3])
+  assert.equal(r.capped, true, '더 있었다는 사실을 말해야 한다')
+})
+
+test('★ 갈래를 섞어도 시각순이 유지된다', () => {
+  const a = [{ n: 1 }, { n: 4 }, { n: 7 }]
+  const b = [{ n: 2 }, { n: 5 }, { n: 8 }]
+  const c = [{ n: 3 }, { n: 6 }, { n: 9 }]
+  const r = mergeStreams([a, b, c], 9, byN)
+  assert.deepEqual(r.items.map(x => x.n), [1, 2, 3, 4, 5, 6, 7, 8, 9])
+  assert.equal(r.capped, false, '상한에 닿지 않았으면 잘리지 않았다')
+})
+
+test('★ 상한에 닿은 갈래가 있으면 잘렸다고 말한다 — 숫자가 알리지 않고 작아지지 않게', () => {
+  /* 한 갈래가 정확히 상한만큼 받아 왔으면 그 갈래에 더 있었을 수 있다. */
+  const r = mergeStreams([seq(1, 3), seq(10, 1)], 3, byN)
+  assert.equal(r.items.length, 3)
+  assert.equal(r.capped, true)
+})
+
+test('상한에 못 닿았고 합쳐도 상한 미만이면 잘리지 않았다', () => {
+  const r = mergeStreams([seq(1, 2), seq(10, 2)], 10, byN)
+  assert.deepEqual(r.items.map(x => x.n), [1, 2, 10, 11])
+  assert.equal(r.capped, false)
+})
+
+test('빈 갈래가 섞여도 답이 같다 — 그 종류가 그 구간에 없는 것은 정상이다', () => {
+  const r = mergeStreams([[], seq(5, 2), []], 10, byN)
+  assert.deepEqual(r.items.map(x => x.n), [5, 6])
+  assert.equal(r.capped, false)
+})
+
+test('★ 갈래가 상한보다 많이 받아 오면 그 사실을 말한다 — 있을 수 없는 일이다', () => {
+  /* 부르는 쪽이 상한을 잘못 걸었다는 뜻이고, 그 상태로 답하면 합친 결과를 믿을 수 없다. */
+  const r = mergeStreams([seq(1, 5)], 3, byN)
+  assert.equal(r.underfilled, true)
+})
+
+test('갈래가 하나면 그냥 앞에서 자른 것과 같다', () => {
+  const r = mergeStreams([seq(1, 5)], 5, byN)
+  assert.deepEqual(r.items.map(x => x.n), [1, 2, 3, 4, 5])
+  assert.equal(r.underfilled, false)
+})

package/test/mirror-resumes-from-checkpoint.test.ts

@@ -1,24 +1,24 @@
 /*
- * ★ **재기동이 저널을 처음부터 다시 접지 않는다** — 미러가 저장된 재개점에서 이어 선다.
+ * ★ **재기동이 저널을 처음부터 다시 계산하지 않는다** — 미러가 저장된 재개점에서 이어 선다.
  *
  * ── 무엇이 오래 잘못돼 있었나 (2026-08-24 실측) ─────────────────────────────
- * 재개점을 **읽는** 쪽은 다 있었다: `recover` 는 `fold` 가 있으면 꼬리만 접고, 없으면 저널을 0부터
- * 접는다. 그런데 **쓰는 쪽이 없었다** — `persistSnapshot` 은 `{revision, state, structureRev}` 만
+ * 재개점을 **읽는** 쪽은 다 있었다: `recover` 는 `fold` 가 있으면 꼬리만 계산하고, 없으면 저널을 0부터
+ * 계산한다. 그런데 **쓰는 쪽이 없었다** — `persistSnapshot` 은 `{revision, state, structureRev}` 만
  * 적었다. 실측으로 저장된 스냅샷 34건 전부 `fold` 가 비어 있었고, 저널은 2,960만 줄이었다.
  *
  * 그래서 두 가지가 함께 일어났다.
  *
- *   ① 켤 때마다 처음부터 접었다 — 규모 기준(엔티티 10만·품목 100만)에서 느린 것이 아니라 못 하는 것이다
+ *   ① 켤 때마다 처음부터 계산했다 — 규모 기준(엔티티 10만·품목 100만)에서 느린 것이 아니라 못 하는 것이다
  *   ② 미러는 되찾은 상태를 **버렸다**(`startLive`). 「다음 계측이 정정한다」는 전제였는데, 원본이 커서
- *      증분으로 말하는 현장에서는 그 정정이 오지 않는다 — 미러가 영구히 빈 채로 남고 화면은 조용했다
+ *      증분으로 말하는 현장에서는 그 정정이 오지 않는다 — 미러가 영구히 빈 채로 남고 화면은 들어온 것이 없었다
  *
  * ── 왜 커널 시험만으로 충분하지 않나 ────────────────────────────────────────
- * 커널은 「재개점 + 꼬리 == 0부터 접기」를 증명한다(`observed-checkpoint.test.ts`). 그것이 참이어도
+ * 커널은 「재개점 + 꼬리 == 0부터 계산하기」를 증명한다(`observed-checkpoint.test.ts`). 그것이 참이어도
  * 호스트가 재개점을 **적지 않거나 되세우지 않으면** 아무 일도 일어나지 않는다 — 이 저장소가 실제로
  * 넉 달 동안 그 상태였다. 그래서 여기서 DB 를 물고 실제로 걷는다.
  *
  * ── 결정적인 단정 ───────────────────────────────────────────────────────────
- * 재기동 전에 **저널을 지운다.** 그래도 상태가 돌아오면 그것은 저널을 접어 온 것이 **아니다** —
+ * 재기동 전에 **저널을 지운다.** 그래도 상태가 돌아오면 그것은 저널을 계산해 온 것이 **아니다** —
  * 저장된 재개점에서 온 것이다. 그리고 그 상황은 가정이 아니라 설계된 거동이다: 보존 정책이 체크포인트
  * 리비전 이하의 행을 지운다(「그 앞은 스냅샷이 대신한다」).
  */
@@ -31,7 +31,7 @@ const req = createRequire(import.meta.url)
 const { NamingStrategy, addDataSource, entities: shellEntities, Domain } = req('@things-factory/shell')
 const { entities: authEntities } = req('@things-factory/auth-base')
 const { entities: twinEntities } = req('../dist-server/service/index.js')
-/* 체크포인트는 `cache-service` 표에 앉는다 — 그 엔티티를 빼면 저장이 조용히 실패한다(스냅샷도 씨앗도). */
+/* 체크포인트는 `cache-service` 표에 앉는다 — 그 엔티티를 빼면 저장이 알리지 않고 실패한다(스냅샷도 씨앗도). */
 const { entities: cacheEntities } = req('@things-factory/cache-service/dist-server/service/index.js')
 const { TwinEngine } = req('../dist-server/engine/index.js')
 const { TwinEvent } = req('../dist-server/service/twin-event/twin-event.js')
@@ -56,7 +56,7 @@ const master = (): any => ({
   equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'dock' }]
 })
 
-/** 원본이 말한 사실 — 오더와 작업. 미러는 이것을 접어 상태를 만든다. */
+/** 원본이 말한 사실 — 오더와 작업. 미러는 이것을 계산해 상태를 만든다. */
 function facts(n: number): any[] {
   const out: any[] = []
   for (let i = 1; i <= n; i++) {
@@ -112,7 +112,7 @@ after(async () => {
   await ds?.destroy()
 })
 
-test('체크포인트가 **이어 접을 씨앗을 함께 적는다** — 이 줄이 없어서 넉 달 동안 처음부터 접었다', async () => {
+test('체크포인트가 **이어 계산할 씨앗을 함께 적는다** — 이 줄이 없어서 넉 달 동안 처음부터 계산했다', async () => {
   const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'resync')
   assert.equal(rt.mode, 'live', '미러로 떠야 이 검사가 뜻이 있다')
 
@@ -124,14 +124,14 @@ test('체크포인트가 **이어 접을 씨앗을 함께 적는다** — 이
   await TwinEngine.persistSnapshot(domainId, INSTANCE)
   const stored = await TwinEngine.loadSnapshot(domainId, INSTANCE)
   assert.ok(stored, '스냅샷이 저장됐다')
-  assert.ok(stored.fold?.reducer, '★ 재개점이 함께 적혀야 한다 — 없으면 다음 기동이 저널을 0부터 접는다')
+  assert.ok(stored.fold?.reducer, '★ 재개점이 함께 적혀야 한다 — 없으면 다음 기동이 저널을 0부터 계산한다')
   assert.ok(stored.fold?.oee, '가동 누적기도 함께 — 상태만 되돌리면 가동률이 부팅 이후로만 잡힌다')
   /* 씨앗이 실제로 사실을 들었는지 — 빈 껍데기를 적어 두고 초록이 되지 않게. */
   assert.ok((stored.fold.reducer as any).orders?.length, '씨앗에 오더가 담겨 있다')
   assert.ok((stored.fold.reducer as any).tasks?.length, '씨앗에 작업이 담겨 있다')
 })
 
-test('★ 저널을 지워도 미러가 상태를 들고 다시 선다 — 그러므로 저널을 접은 것이 아니다', async () => {
+test('★ 저널을 지워도 미러가 상태를 들고 다시 선다 — 그러므로 저널을 계산한 것이 아니다', async () => {
   /*
    * 이 단정이 이 축의 전부다. 저널이 없는데 상태가 돌아오면 그 상태는 **저장된 재개점**에서 온 것이다.
    * 그리고 이 상황은 가정이 아니다 — 보존 정책이 체크포인트 리비전 이하의 행을 실제로 지운다.
@@ -145,7 +145,7 @@ test('★ 저널을 지워도 미러가 상태를 들고 다시 선다 — 그
   assert.equal(
     await ds.getRepository(TwinEvent).countBy({ domain: { id: domainId } as any, instanceId: INSTANCE } as any),
     0,
-    '저널이 비었다 — 이제 접을 것이 없다'
+    '저널이 비었다 — 이제 계산할 것이 없다'
   )
 
   await TwinEngine.bootDeclared(domainId, INSTANCE, 'resync')

package/test/model-basis.test.ts

@@ -131,11 +131,11 @@ test('선언이 침묵하면 기본값으로 떨어진다 — 없는 것을 지
   assert.equal(modelBasisChanged(quiet(base), quiet(base * 1.3)), true, '기본 10% 밖')
 })
 
-test('변동폭이 바뀌면 다른 모델이다 — 판정의 잣대가 조용히 바뀌지 않게', () => {
+test('변동폭이 바뀌면 다른 모델이다 — 판정의 잣대가 알리지 않고 바뀌지 않게', () => {
   const a = weld(70 * 60_000)
   const b = {
     measured: { weld: 70 * 60_000 },
     declared: [{ key: 'weld', duration: 'PT1H10M', variability: { distribution: 'triangular', min: 'PT30M', max: 'PT3H', mode: 'PT1H5M' } }]
   }
-  assert.equal(modelBasisChanged(a, b), true, '변동폭 선언이 바뀌었는데 같은 모델이라고 하면 잣대가 조용히 바뀐다')
+  assert.equal(modelBasisChanged(a, b), true, '변동폭 선언이 바뀌었는데 같은 모델이라고 하면 잣대가 오류 없이 바뀐다')
 })

package/test/model-gap.test.ts

@@ -20,7 +20,7 @@
  * ── 지키는 것 ───────────────────────────────────────────────────────────────
  * ① 마스터가 말한 것과 관측으로 알게 된 것을 섞지 않는다
  * ② 트윈이 안 돌면 `null` — 「없다」와 「세어 보지 못했다」는 다르다
- * ③ 조용히 자르지 않는다 — 상한에서 밀려난 수를 함께 낸다
+ * ③ 알리지 않고 자르지 않는다 — 상한에서 밀려난 수를 함께 낸다
  * ④ 덮지 못하는 축을 밝힌다 — 계량기는 커널이 표시를 달지 않아 이 화면이 못 찾아 준다
  */
 import { test } from 'node:test'
@@ -68,7 +68,7 @@ test('돌지만 관측 갭이 없으면 0 이다 — 이건 「없음」과 다
   assert.equal(g!.total, 0, '세어 보니 없었다')
 })
 
-test('id 를 조용히 자르지 않는다 — 밀려난 수를 함께 낸다', () => {
+test('id 를 알리지 않고 자르지 않는다 — 밀려난 수를 함께 낸다', () => {
   const many = Array.from({ length: GAP_ID_LIMIT + 7 }, (_, i) => loc(`ghost-${i}`, 'observed'))
   const g = modelGapOf({ locations: many })
 
@@ -95,7 +95,7 @@ test('모르는 설비의 에너지 보고는 「없음」과 0 을 가른다
   /*
    * 이 값을 **루트에서 읽고 있었다**(2026-08-20에 잡음). 커널은 `EnergyState` 안에 담으므로 루트에서
    * 읽으면 영원히 `null` 이고, 오류 없이 「에너지 트윈이 아니다」로 읽힌다. 나만 읽는 필드를 잘못된
-   * 경로에서 읽으면 이렇게 조용히 사라진다.
+   * 경로에서 읽으면 이렇게 오류 없이 사라진다.
    *
    * 그리고 커널은 0 이면 그 칸을 만들지 않는다. 그래서 `energy` 자체가 있는지로 「세었고 0」과
    * 「에너지 트윈이 아님」을 가른다.
@@ -112,7 +112,7 @@ test('모르는 설비의 에너지 보고는 「없음」과 0 을 가른다
 
 test('계량기도 덮는다 — 이 축이 가장 무겁다', () => {
   /*
-   * 모르는 `meterId` 는 조용히 새 계량기가 되고 그 kW 가 그 현장의 수요·피크·요금 판정에 더해진다.
+   * 모르는 `meterId` 는 알리지 않고 새 계량기가 되고 그 kW 가 그 현장의 수요·피크·요금 판정에 더해진다.
    * 로케이션 오타는 스키매틱이 비는 것으로 드러나지만, 이건 **그럴듯한 숫자**로 나온다.
    * 커널 0.7.39 가 `MeterPointState.origin` 을 내면서 덮을 수 있게 됐다.
    */

package/test/model-vocabulary.test.ts

@@ -4,7 +4,7 @@
  * ── 계기 (2026-08-06, 사용자 신고) ───────────────────────────────────────────
  * 모델러의 엔티티 목록이 통째로 비어 있었다. **오류는 없었다.** 저장된 모델가 옛 어휘(`nodes`/`movers`)
  * 인데 화면과 호스트가 새 어휘를 읽었기 때문이다. 같은 원인이 구조 서명(`N[]M[]` — 서로 다른 두 공장이
- * 같아 보인다)·주행 추정기·설비 동기까지 조용히 망가뜨리고 있었다.
+ * 같아 보인다)·주행 추정기·설비 동기까지 알리지 않고 망가뜨리고 있었다.
  *
  * 그래서 **DB에서 읽는 순간** 한 번 정규화한다. 이 테스트가 지키는 것은 그 정규화가 ① 세 세대를 다
  * 흡수하고 ② 나머지 속성을 하나도 잃지 않고 ③ 새 모델에는 아무 일도 하지 않는 것이다.
@@ -101,7 +101,7 @@ test('두 옛 모델이 구조적으로 구별된다 — 서명이 빈 문자열
 })
 
 test('보드를 저장하는 엔티티가 **변환기를 달고 있다** — 결선이 빠지면 순수 모듈은 그린인데 화면은 빈다', () => {
-  /* 이 결함이 정확히 그랬다: 리더는 커널에 있었고 목록만 그것을 거쳤다. 결선은 조용히 빠질 수 있으므로
+  /* 이 결함이 정확히 그랬다: 리더는 커널에 있었고 목록만 그것을 거쳤다. 결선은 알리지 않고 빠질 수 있으므로
      기계가 지킨다. 새 엔티티가 보드를 담게 되면 여기 함께 올린다. */
   const owners = ['server/service/twin-instance/twin-instance.ts', 'server/service/twin-structure/twin-structure.ts']
 

package/test/move-space.test.ts

@@ -25,7 +25,7 @@ test('잃을 것이 없으면 경고도 없다 — 정상 경로를 시끄럽게
   assert.deepEqual(j.warnings, [])
 })
 
-test('없는 현장으로는 옮기지 않는다 — 조용히 새 공간을 만들지 않는다', () => {
+test('없는 현장으로는 옮기지 않는다 — 알리지 않고 새 공간을 만들지 않는다', () => {
   const j = judgeMoveTwinSpace({ ...CLEAN, toSpaceExists: false })
   assert.equal(j.refusal?.code, 'space-not-found')
   assert.equal(j.refusal?.params?.spaceId, 'rosarito-site')

package/test/oee-accumulator.test.ts

@@ -108,7 +108,7 @@ test('★ withLiveOee: projector 미러(oee 없음) + 누적기 → live 설비
 /*
  * ── 되짚은 화면에도 가동 이력이 있어야 한다 (2026-08-05) ────────────────────
  * OEE 는 원 시스템이 누적을 보내 주지 않아 호스트가 상태 전이를 적분해 만든다. 그런데 그 누적기는
- * **라이브에서만** 돌았고, 저널을 접는 경로는 그 계산을 하지 않았다 — 과거를 되짚으면 모든 설비가
+ * **라이브에서만** 돌았고, 저널을 계산하는 경로는 그 계산을 하지 않았다 — 과거를 되짚으면 모든 설비가
  * "가동 이력이 전혀 없음" 으로 보였다(실 저널: `rosarito-mes` 18대, `hatiolab-wms` 22대가 그랬다).
  *
  * 없는 것은 데이터가 아니라 계산이다: 입력은 저널에 다 있다. 그래서 같은 누적기에 같은 이벤트를
@@ -174,7 +174,7 @@ test('★ 계측 시점을 벽시계로 재지 않는다 — 과거 화면의
  *
  * 예전에는 `metricsSinceMs: 0` 을 돌려줬다. 시각이 epoch 밀리초라서 그 창은 곧 "1970년부터" 가 되고,
  * 공식의 분모가 지금 시각 전체가 된다 — 화면에 `idleMs 1767226603000`(약 56,000년) 유휴가 섰다.
- * 그 값은 availability·overall 의 분모이기도 해서 **성과 숫자 전체가 조용히 거짓**이 됐다.
+ * 그 값은 availability·overall 의 분모이기도 해서 **성과 숫자 전체가 알리지 않고 거짓**이 됐다.
  */
 test('이벤트를 못 본 설비는 계측 창을 만들지 않는다 — epoch 를 창으로 삼지 않는다', () => {
   const acc = new OeeAccumulator()

package/test/operational-vocabulary.test.ts

@@ -56,7 +56,7 @@ test('거부는 이유와 함께 남는다 — 유효한 것은 함께 통과한
   const { accepted, rejected } = ingestCanonicalRecords(
     [
       { taskId: 'tk-1', kind: 'pick', status: 'completed' },
-      { taskId: 'tk-2', kind: 'pick', status: 'FINISHED' } // 커널이 접을 수 없는 낱말
+      { taskId: 'tk-2', kind: 'pick', status: 'FINISHED' } // 커널이 다룰 수 없는 낱말
     ] as any,
     'domain-1',
     AT
@@ -66,7 +66,7 @@ test('거부는 이유와 함께 남는다 — 유효한 것은 함께 통과한
   assert.ok(rejected[0].errors.join(' ').length > 0)
 })
 
-test('피드 결선이 거부를 조용히 버리지 않는다 — 이유를 사람에게 말한다', () => {
+test('피드 결선이 거부를 알리지 않고 버리지 않는다 — 이유를 사람에게 말한다', () => {
   const src = readFileSync(fileURLToPath(new URL('../server/service/reference/reference-live.ts', import.meta.url)), 'utf-8')
   assert.match(src, /record\(s\) rejected/, '거부 수와 이유를 남긴다')
 })

package/test/project-structure-db.test.ts

@@ -12,7 +12,7 @@
  *  · 끊어진 참조는 **이름을 대고 보고**되고, 행 자체는 남는다(막지 않되 침묵하지 않는다)
  *  · **전량 교체** — 두 번 돌려도 늘지 않고, 원본에서 사라진 것은 행에서도 사라진다
  *  · 원본 표식(`sourceRef`·`ingestedAt`) 없는 행은 만들 수 없다(캐시라는 사실이 구조로 지켜진다)
- *  · 소요시간은 ISO 8601 **문자열 그대로** 남는다(분으로 접으면 초가 조용히 사라진다)
+ *  · 소요시간은 ISO 8601 **문자열 그대로** 남는다(분으로 줄이면 초가 오류 없이 사라진다)
  */
 import { test, before, after, beforeEach } from 'node:test'
 import assert from 'node:assert/strict'
@@ -161,7 +161,7 @@ test('원본 표식 없는 행은 만들 수 없다 — 캐시라는 사실이
   )
 })
 
-test('소요시간은 ISO 8601 문자열 그대로 — 분으로 접으면 초가 조용히 사라진다', async () => {
+test('소요시간은 ISO 8601 문자열 그대로 — 분으로 줄이면 초가 오류 없이 사라진다', async () => {
   const op = await ds.getRepository(TwinOperation).findOne({ where: { operationKey: 'cut' } })
   assert.equal(op?.duration, 'PT1H10M30S')
   /* 변동성·파라미터는 도메인마다 형이 달라 원형 그대로 싣는다. */

package/test/projection-reaches-screen.test.ts

@@ -16,7 +16,7 @@
  * 것은 "이 사실이 여기 앉는다" 는 선언이고, 앉을 자리를 만들어 두고 안 채우면 그 컬럼은 영원히 빈다.
  *
  * 그래서 컬럼마다 셋을 요구한다:
- *   ① 픽스처가 모델에 그 값을 싣는다(값을 줄 방법을 모르면 **검사가 실패한다** — 조용히 건너뛰면
+ *   ① 픽스처가 모델에 그 값을 싣는다(값을 줄 방법을 모르면 **검사가 실패한다** — 알리지 않고 건너뛰면
  *      그 컬럼은 아무도 안 보는 컬럼이 된다)
  *   ② 투영을 지나 행에 남는다
  *   ③ 조회 응답에 나온다(화면이 읽는 자리)
@@ -131,7 +131,7 @@ function master(): any {
       assert.ok(
         col in VALUE,
         `픽스처가 "${c.axis}.${col}" 에 실을 값을 모른다 — VALUE 에 하나 적어라(모델의 사실이 아니면 NOT_FROM_MODEL 에 이유와 함께).\n` +
-          '조용히 건너뛰면 그 컬럼은 아무도 안 보는 컬럼이 되고, 그것이 이 하네스가 막으려는 실패다.'
+          '알리지 않고 건너뛰면 그 컬럼은 아무도 안 보는 컬럼이 되고, 그것이 이 하네스가 막으려는 실패다.'
       )
       o[col] = VALUE[col]
     }

package/test/property-effects.test.ts

@@ -4,7 +4,7 @@
  * ── 왜 이 시험이 있나 (2026-08-18) ──────────────────────────────────────────
  * 화면은 속성마다 「무엇을 바꾸나」를 말한다. 등록되지 않은 속성에는 「표시만 됩니다」라고 한다 — 그것이
  * 정직한 기본값이다. 그런데 에너지 값들(계약전력·정격·요금)은 **오래전부터 읽히고 있었는데** 등록부에
- * 없었다: 사용자는 계약전력을 넣고도 「이 값은 아무것도 바꾸지 않는다」는 문장을 읽었다. 조용한 거짓말이다.
+ * 없었다: 사용자는 계약전력을 넣고도 「이 값은 아무것도 바꾸지 않는다」는 문장을 읽었다. 들어온 것이 없는 거짓말이다.
  *
  * 반대 방향의 위험도 있다: 효과를 등록해 두고 **읽는 코드가 없으면** 화면이 「쓰입니다」라고 말하는데
  * 아무 일도 일어나지 않는다. 그래서 등록부의 각 줄이 가리키는 자리를 이 시험이 확인한다.
@@ -65,7 +65,7 @@ test('축으로 갈라 낸다 — 그 축의 항목에만 효과를 말한다',
 test('요금은 커널이 아니라 호스트가 읽는다 — 그 사실을 readBy 가 말한다', () => {
   const tariff = PROPERTY_EFFECTS.filter(e => e.id.startsWith('tariff.'))
   assert.equal(tariff.length, 3)
-  for (const e of tariff) assert.match(e.readBy, /kpi-query/, '금액은 저널을 접는 쪽이 만든다')
+  for (const e of tariff) assert.match(e.readBy, /kpi-query/, '금액은 저널을 계산하는 쪽이 만든다')
 })
 
 /*
@@ -110,7 +110,7 @@ test('수율·셋업이 커널 창구까지 배선돼 있다 — 등록만 하
   const divisions = layer.match(/pct \/ 100/g) ?? []
   assert.equal(divisions.length, 1, `퍼센트 환산은 한 자리에서만 (발견 ${divisions.length})`)
   assert.match(hostSrc('engine/twin-engine.ts'), /declareParameters\(params\)/, '기동·구조전환 때 커널에 싣는다')
-  /* 커널이 그 창구를 갖지 않은 버전이면 **말한다** — 조용히 상수로 돌지 않게. */
+  /* 커널이 그 창구를 갖지 않은 버전이면 **말한다** — 알리지 않고 상수로 돌지 않게. */
   assert.match(hostSrc('engine/twin-engine.ts'), /declareParameters missing/, '버전 어긋남을 경고로 드러낸다')
 })
 

package/test/read-failure-ledger.test.ts

@@ -0,0 +1,106 @@
+/*
+ * ★ 연결된 시스템에 닿지 못한 것과 다시 닿은 것을 인제스트 레저가 기록한다.
+ *
+ * ── 무엇이 없었나 (2026-08-27) ──────────────────────────────────────────────
+ * 커넥터는 폴링이 실패할 때 세 가지를 안다: 연달아 몇 번인지 · 언제부터인지 · 다음에 언제 다시 묻는지.
+ * 그런데 어댑터 계약에는 이유 한 줄만 받는 자리가 있었다. 그래서 커넥터가 세 가지를 **한국어 문장으로
+ * 합쳐** 이유 칸에 넣고 있었다(`ppms-sunsage.ts`).
+ *
+ * 두 가지가 틀어진다.
+ *   ① 연달아 횟수와 시작 시각은 이 레저가 **이미 센다**. 두 곳에서 세면 갈라진다.
+ *   ② 그 칸은 화면에 그려지고 화면은 다섯 언어로 그린다. 한 언어의 문장은 번역되지 않는다.
+ *
+ * 그리고 회복을 받는 자리가 아예 없었다. 읽기가 다시 성공하면 실패 기록만 지워졌고, 그러면 밤새 두 시간
+ * 끊겼던 연결과 한 번도 끊기지 않은 연결이 아침에 똑같이 보인다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  newIngestLedger,
+  recordReadFailure,
+  recordRecovered,
+  clearReadFailure,
+  ingestHealth
+} from '../server/engine/ingest-health.js'
+
+const t0 = Date.UTC(2026, 7, 27, 3, 0, 0)
+
+test('★ 연달아 실패한 횟수와 시작 시각은 레저가 센다 — 커넥터가 보내지 않는다', () => {
+  const l = newIngestLedger()
+  recordReadFailure(l, 'connect timeout', t0, 'inverters')
+  recordReadFailure(l, 'connect timeout', t0 + 60_000, 'inverters')
+  recordReadFailure(l, 'connect timeout', t0 + 120_000, 'inverters')
+  assert.equal(l.readFailure?.consecutive, 3)
+  assert.equal(l.readFailure?.sinceMs, t0, '처음 실패한 시각을 붙잡는다')
+  assert.equal(l.readFailure?.lastAtMs, t0 + 120_000)
+})
+
+test('★ 이유는 이유만 담는다 — 세는 값을 문장으로 합쳐 넣지 않는다', () => {
+  /*
+   * 이 테스트는 사람이 읽는 문장이 이유 칸에 들어가는 것을 막지 못한다(문자열은 무엇이든 담긴다).
+   * 막을 수 있는 것은 **그 값들을 담을 다른 자리가 있다**는 사실뿐이다. 그것을 테스트로 고정한다.
+   */
+  const l = newIngestLedger()
+  recordReadFailure(l, 'connect timeout', t0, 'inverters', 480_000)
+  assert.equal(l.readFailure?.reason, 'connect timeout')
+  assert.equal(l.readFailure?.nextRetryMs, 480_000)
+})
+
+test('다음 시도까지의 시간은 있을 때만 적는다 — 0 이나 없는 값을 「곧 다시 묻는다」로 만들지 않는다', () => {
+  const l = newIngestLedger()
+  recordReadFailure(l, 'connect timeout', t0)
+  assert.equal('nextRetryMs' in (l.readFailure as any), false)
+  recordReadFailure(l, 'connect timeout', t0 + 1000, undefined, 0)
+  assert.equal('nextRetryMs' in (l.readFailure as any), false)
+})
+
+test('★ 돌아오면 실패 기록이 사라지고 돌아온 사실이 남는다', () => {
+  const l = newIngestLedger()
+  recordReadFailure(l, 'connect timeout', t0)
+  recordReadFailure(l, 'connect timeout', t0 + 60_000)
+  recordRecovered(l, 2, 120_000, t0 + 120_000)
+  assert.equal(l.readFailure, undefined, '지금은 닿는다')
+  assert.deepEqual(l.lastRecovery, { atMs: t0 + 120_000, afterFailures: 2, downMs: 120_000 })
+})
+
+test('★ 그냥 지우면 끊긴 적이 있었다는 사실이 사라진다 — 그래서 두 함수를 나눈다', () => {
+  const l = newIngestLedger()
+  recordReadFailure(l, 'connect timeout', t0)
+  clearReadFailure(l)
+  assert.equal(l.readFailure, undefined)
+  assert.equal(l.lastRecovery, undefined, '지우기만 하면 남지 않는다')
+})
+
+test('★ 다시 끊기면 새 단절이다 — 지난번 회복 기록이 그것을 가리지 않는다', () => {
+  const l = newIngestLedger()
+  recordReadFailure(l, 'connect timeout', t0)
+  recordRecovered(l, 1, 60_000, t0 + 60_000)
+  recordReadFailure(l, '401 unauthorized', t0 + 600_000)
+  assert.equal(l.readFailure?.consecutive, 1, '연달아 횟수가 1 부터 다시 센다')
+  assert.equal(l.readFailure?.sinceMs, t0 + 600_000)
+  assert.equal(l.lastRecovery?.atMs, t0 + 60_000, '지난 회복도 함께 보인다')
+})
+
+test('★ 밖으로 내는 모양에 두 사실이 다 있다 — 화면이 옮기지 못하면 아무 도움이 되지 않는다', () => {
+  const l = newIngestLedger()
+  recordReadFailure(l, 'connect timeout', t0, 'inverters', 480_000)
+  const v: any = ingestHealth(l, 'attached')
+  assert.equal(v.readFailure.consecutive, 1)
+  assert.equal(v.readFailure.reason, 'connect timeout')
+  assert.equal(v.readFailure.stream, 'inverters')
+  assert.equal(v.readFailure.nextRetryMs, 480_000)
+  assert.equal(typeof v.readFailure.since, 'string')
+
+  recordRecovered(l, 1, 480_000, t0 + 480_000)
+  const w: any = ingestHealth(l, 'attached')
+  assert.equal(w.readFailure, undefined)
+  assert.equal(w.lastRecovery.at, new Date(t0 + 480_000).toISOString())
+  assert.equal(w.lastRecovery.afterFailures, 1)
+  assert.equal(w.lastRecovery.downMs, 480_000)
+})
+
+test('닿은 적도 끊긴 적도 없으면 두 칸이 다 없다 — 없는 칸을 「끊겼다」로 읽지 않게', () => {
+  const v: any = ingestHealth(newIngestLedger(), 'attached')
+  assert.equal('readFailure' in v, false)
+  assert.equal('lastRecovery' in v, false)
+})

package/test/read-failure-visible.test.ts

@@ -1,7 +1,7 @@
 /*
- * ★ 「원본에 닿지 못한다」와 「원본이 조용하다」는 **다른 사실**이다 — 상태가 그것을 가려야 한다.
+ * ★ 「원본에 닿지 못한다」와 「연결된 시스템에서 들어온 것이 없다」는 **다른 사실**이다 — 상태가 그것을 가려야 한다.
  *
- * ── 무엇이 조용했나 (2026-08-23 실측) ───────────────────────────────────────
+ * ── 무엇이 아무 신호도 내지 않았나 (2026-08-23 실측) ───────────────────────────────────────
  * 실 원본이 끊겼다(`jejoup.hatiolab.com:4000` 접속 시간 초과, HTTP 000 / 8초). 그런데 트윈의
  * **조회 가능한 상태 어디에도 그 사실이 없었다.**
  *
@@ -14,7 +14,7 @@
  *
  * ── 이 시험이 지키는 것 ─────────────────────────────────────────────────────
  * ① 실패가 상태에 남는다  ② 「몇 번」과 「언제부터」를 함께 든다(한 번의 흔들림과 20분째 단절은 다르다)
- * ③ **빈 읽기는 성공이다** — 조용한 원본을 끊긴 원본으로 만들지 않는다
+ * ③ **빈 읽기는 성공이다** — 들어온 것이 없는 연결을 끊긴 원본으로 만들지 않는다
  * ④ 조회 뷰로 나간다 — 상태에만 있고 안 나가면 화면이 못 본다
  */
 import { test } from 'node:test'
@@ -53,7 +53,7 @@ test('한 번의 흔들림과 20분째 단절을 가른다 — 시작 시각을
   assert.equal(l.readFailure?.lastAtMs, T0 + 1_200_000, '마지막 실패는 갱신된다')
 })
 
-test('빈 읽기는 성공이다 — 조용한 원본을 끊긴 원본으로 만들지 않는다', () => {
+test('빈 읽기는 성공이다 — 들어온 것이 없는 연결을 끊긴 원본으로 만들지 않는다', () => {
   /*
    * ★ 이 단정이 고치려던 것의 **반대 방향으로 틀리는 것**을 막는다. 원본이 「새 것이 없다」고 답한 것은
    * 닿았다는 뜻이다.
@@ -90,7 +90,7 @@ test('닿고 있으면 그 필드를 만들지 않는다 — 빈 값이 「닿
 
 test('「유입 없음」과 「닿지 못함」은 다른 판정이다', () => {
   /*
-   * 유입 없음은 원본이 조용한 것일 수 있고, 닿지 못함은 우리가 묻지도 못한 것이다. 두 상태가 같은
+   * 유입 없음은 연결된 시스템에서 들어온 것이 없는 것일 수 있고, 닿지 못함은 우리가 묻지도 못한 것이다. 두 상태가 같은
    * 값으로 뭉개지면 화면이 두 문장을 다르게 말할 수 없다.
    */
   const quiet = newIngestLedger()
@@ -99,7 +99,7 @@ test('「유입 없음」과 「닿지 못함」은 다른 판정이다', () =>
 
   const vq = ingestHealth(quiet, 'attached', undefined, T0)
   const vd = ingestHealth(dark, 'attached', undefined, T0)
-  assert.equal(vq.lastAt, null, '조용한 쪽도 받은 것이 없다')
+  assert.equal(vq.lastAt, null, '들어온 것이 없는 쪽도 받은 것이 없다')
   assert.equal(vd.lastAt, null, '끊긴 쪽도 받은 것이 없다 — 그 값만으로는 갈리지 않는다')
   assert.notEqual(Boolean(vq.readFailure), Boolean(vd.readFailure), '이 축이 그 둘을 가른다')
 })
@@ -117,7 +117,7 @@ test('「유입 없음」과 「닿지 못함」은 다른 판정이다', () =>
  *   status      **연결 설정이 성립하나** — 접속 시험·마스터 동기가 정한다. 재부착의 **자격**이다
  *   읽기 실패    **지금 닿나** — 오갈 수 있는 사실이고 유입 장부가 그 축을 갖는다
  *
- * 「사실을 말하게」 하려던 것이 「사실을 못 듣게」 만들었다. 그 방향의 실패는 조용하다 — 화면은
+ * 「사실을 말하게」 하려던 것이 「사실을 못 듣게」 만들었다. 그 방향의 실패는 들어온 것이 없다 — 화면은
  * 「원본에 닿지 못한다」를 정직하게 말하면서, 정작 다시 닿을 기회를 잃는다.
  */
 test('읽기 실패가 레퍼런스의 status 를 건드리지 않는다 — 그것이 재부착의 자격이다', () => {

package/test/read-time.test.ts

@@ -0,0 +1,118 @@
+/*
+ * ★ 저장된 값을 시각으로 읽는 규칙 — 드라이버의 문을 지난다.
+ *
+ * ── 무엇이 어긋났나 (2026-08-28 실측) ───────────────────────────────────────
+ * `getRawOne` 은 드라이버가 준 값을 그대로 준다. sqlite 가 주는 그 값에는 시간대가 없다
+ * (`2026-08-27 14:37:20.049`). 그것을 `new Date()` 로 읽으면 서버의 지역 시간으로 해석해 한국에서
+ * 9시간이 밀린다. 네 자리에서 났고, 둘은 **지우는 경계**였다(경계가 이르게 밀리면 정리가 0건이 되어
+ * 멈춘다).
+ *
+ * ── 처음에 편법을 썼다 ──────────────────────────────────────────────────────
+ * 「시간대가 없으면 UTC 로 읽는다」를 응용 코드에 직접 적었다. 그것은 드라이버가 어떤 문자열로
+ * 저장하는지를 우리가 아는 것이고, 다섯 드라이버 규칙에 어긋난다.
+ *
+ * 표준 문은 `Driver.prepareHydratedValue` 다 — 엔티티 변환이 지나는 그 함수. 이 시험은 컬럼 값을
+ * 읽을 때 **우리가 해석하지 않고 그 문에 물어보는지**를 지킨다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { absoluteTime, hydratedDate } from '../server/engine/read-time.js'
+
+/** 드라이버를 흉내낸 저장소 — 이 시험이 확인하는 것은 「누가 해석하나」다. */
+const fakeRepository = (opts: { hasColumn?: boolean; hydrate?: (v: unknown) => unknown } = {}) => {
+  const calls: unknown[] = []
+  const repo = {
+    metadata: {
+      name: 'TwinEvent',
+      findColumnWithPropertyName: (name: string) => (opts.hasColumn === false ? undefined : { propertyName: name, type: Date })
+    },
+    manager: {
+      connection: {
+        driver: {
+          prepareHydratedValue: (value: unknown) => {
+            calls.push(value)
+            return opts.hydrate ? opts.hydrate(value) : new Date('2026-08-27T14:37:20.049Z')
+          }
+        }
+      }
+    }
+  }
+  return { repo: repo as any, calls }
+}
+
+test('★ 컬럼 값은 우리가 해석하지 않고 드라이버에게 물어본다', () => {
+  const { repo, calls } = fakeRepository()
+  const at = hydratedDate(repo, 'createdAt', '2026-08-27 14:37:20.049')
+  assert.equal(at?.toISOString(), '2026-08-27T14:37:20.049Z')
+  assert.deepEqual(calls, ['2026-08-27 14:37:20.049'], '드라이버의 문을 그 값으로 한 번 지나야 한다')
+})
+
+test('빈 값은 드라이버를 부르지 않고 null — 없는 것은 없는 것이다', () => {
+  const { repo, calls } = fakeRepository()
+  assert.equal(hydratedDate(repo, 'createdAt', null), null)
+  assert.equal(hydratedDate(repo, 'createdAt', undefined), null)
+  assert.deepEqual(calls, [])
+})
+
+test('드라이버가 날짜를 내주지 못하면 null — 「지금」으로 메우지 않는다', () => {
+  const { repo } = fakeRepository({ hydrate: () => 'still a string' })
+  assert.equal(hydratedDate(repo, 'createdAt', 'x'), null)
+  const bad = fakeRepository({ hydrate: () => new Date('nope') })
+  assert.equal(hydratedDate(bad.repo, 'createdAt', 'x'), null)
+})
+
+test('★ 컬럼 이름을 못 찾으면 명시 실패한다 — 이름이 바뀐 것을 값으로 덮지 않는다', () => {
+  const { repo } = fakeRepository({ hasColumn: false })
+  assert.throws(() => hydratedDate(repo, 'createdAt', '2026-08-27 14:37:20.049'), /no column for property/)
+})
+
+test('★ 계약이 절대시각인 값 — 시간대가 없으면 UTC 다(지역 시간으로 읽을 근거가 없다)', () => {
+  assert.equal(absoluteTime('2026-08-27 14:37:20.049')?.toISOString(), '2026-08-27T14:37:20.049Z')
+  /* 지역 시간으로 읽었다면 한국에서 9시간이 밀린다. */
+  assert.notEqual(absoluteTime('2026-08-27 14:37:20.049')?.toISOString(), '2026-08-27T05:37:20.049Z')
+})
+
+test('시간대가 적혀 있으면 그 말을 믿는다', () => {
+  assert.equal(absoluteTime('2026-08-27T14:37:20.049Z')?.toISOString(), '2026-08-27T14:37:20.049Z')
+  assert.equal(absoluteTime('2026-08-27T23:37:20.049+09:00')?.toISOString(), '2026-08-27T14:37:20.049Z')
+  assert.equal(absoluteTime('2026-08-27T09:37:20.049-05:00')?.toISOString(), '2026-08-27T14:37:20.049Z')
+})
+
+test('날짜 객체와 밀리초도 받는다', () => {
+  const d = new Date('2026-08-27T14:37:20.049Z')
+  assert.equal(absoluteTime(d), d)
+  assert.equal(absoluteTime(1_756_305_440_049)?.getTime(), 1_756_305_440_049)
+})
+
+test('★ 읽을 수 없는 값은 null — 경계를 정하는 자리가 이 함수를 쓴다', () => {
+  for (const bad of [null, undefined, '', '   ', '어제', 'not-a-date', {}, [], NaN, new Date('x')]) {
+    assert.equal(absoluteTime(bad), null, `${String(bad)} 는 null 이어야 한다`)
+  }
+})
+
+test('★ 컬럼 값을 직접 날짜로 만드는 자리가 남아 있지 않다', () => {
+  /*
+   * 규칙이 있어도 새로 쓰는 코드가 그것을 지나지 않으면 같은 결함이 다시 난다. 그래서 자리를 세어
+   * 둔다 — 원시 결과의 컬럼을 `new Date(...)` 로 감싸는 모양을 찾는다.
+   *
+   * 밀리초 숫자(`new Date(someMs)`)는 시간대가 없으므로 이 그물에 걸리지 않는다.
+   */
+  const root = join(import.meta.dirname, '..', 'server')
+  const offenders: string[] = []
+  const walk = (dir: string) => {
+    for (const name of readdirSync(dir)) {
+      const p = join(dir, name)
+      if (statSync(p).isDirectory()) { walk(p); continue }
+      if (!name.endsWith('.ts')) continue
+      const text = readFileSync(p, 'utf8')
+      for (const m of text.matchAll(/new Date\(\s*[A-Za-z_$][\w$?.]*\.(eventTime|createdAt|updatedAt|at)\b[^)]*\)/g)) {
+        offenders.push(`${name}: ${m[0]}`)
+      }
+    }
+  }
+  walk(root)
+  assert.deepEqual(offenders, [], '컬럼 값을 직접 날짜로 만드는 자리가 있다 — hydratedDate() 를 지나야 한다')
+})

package/test/reference-grounding.test.ts

@@ -59,7 +59,7 @@ test('목과 가상은 대상 없이도 선다 — 그 자체가 사실이다',
 test('instance 와 product 를 가른다 — 그 구분이 이 어휘의 요점이다', () => {
   /*
    * 첫 실 연동에서 그 배포만의 성질이 넷 드러났는데(관계 리솔버가 다른 테넌트의 행을 답한다 · 모르는
-   * 필터를 조용히 무시한다 · 지워진 품목의 BOM 이 남아 있다 · 사실상 무한을 뜻하는 표식) **그것이
+   * 필터를 알리지 않고 무시한다 · 지워진 품목의 BOM 이 남아 있다 · 사실상 무한을 뜻하는 표식) **그것이
    * 제품의 성질인지 그 인스턴스의 성질인지 아무도 모른다.** 두 번째 배포가 붙는 날 갈린다.
    *
    * 그래서 하나로 확인한 것을 `product` 라 부르면 안 되고, 어휘가 그 구분을 담는다.