@things-factory/headless-twin 10.0.12 → 10.0.13

package/test/log-stamp.test.ts

@@ -0,0 +1,59 @@
+/*
+ * 로그에 **시각이 있다** — 그리고 어떤 인자도 버리지 않는다 (2026-08-22).
+ *
+ * 루프가 55초 막힌 것을 계기로 알아냈는데 그 시각에 무슨 일이 있었는지 로그에서 찾을 수 없었다.
+ * 트윈의 줄이 `console.log` 로 나가 시각이 없었기 때문이다. 이 시험이 지키는 것:
+ *  ① 형식 — 프레임워크 줄과 같은 모양, **밀리초까지**(계기의 값이 epoch ms 다)
+ *  ② 지역 시각 — 프레임워크의 다른 줄과 같은 기준(UTC 로 찍으면 나란히 읽을 수 없다)
+ *  ③ 인자를 버리지 않는다 — 오류는 스택까지(`console.error(msg, err)` 로 쓰던 자리가 많다)
+ *  ④ 트윈 소스에 `console.` 직접 호출이 남지 않는다 — 하나라도 남으면 그 줄만 시각이 없다
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { line, stamp } from '../server/engine/log.ts'
+
+test('시각은 밀리초와 오프셋까지 적는다 — 같은 초 안의 순서를 가릴 수 있게', () => {
+  const s = stamp(new Date(2026, 7, 22, 5, 54, 12, 345))
+  assert.match(s, /^2026-08-22T05:54:12\.345[+-]\d\d:\d\d$/, `형식이 다르다: ${s}`)
+})
+
+test('지역 시각으로 적는다 — 프레임워크의 다른 줄과 같은 기준', () => {
+  const at = new Date(2026, 0, 2, 3, 4, 5, 6)
+  const s = stamp(at)
+  assert.ok(s.startsWith('2026-01-02T03:04:05.006'), `지역 시각이 아니다: ${s}`)
+})
+
+test('오류는 스택까지 남는다 — 「어디서 났나」를 잃지 않게', () => {
+  const err = new Error('불이 났다')
+  const out = line(['[twin-engine] 저장 실패', err])
+  assert.ok(out.includes('[twin-engine] 저장 실패'))
+  assert.ok(out.includes('불이 났다'))
+  assert.ok(out.includes('log-stamp.test'), '스택이 있어야 어느 자리에서 났는지 알 수 있다')
+})
+
+test('값이 없어도 있었다는 사실은 남긴다 — 조용히 지우지 않는다', () => {
+  assert.equal(line(['a', undefined, null, 0]), 'a undefined null 0')
+  const circular: any = { name: 'ㄱ' }
+  circular.self = circular
+  assert.ok(line(['보고', circular]).startsWith('보고 '), '순환 참조에도 줄이 남아야 한다')
+})
+
+test('트윈 소스에 console 직접 호출이 남아 있지 않다 — 한 줄이라도 남으면 그 줄만 시각이 없다', () => {
+  const root = fileURLToPath(new URL('../server/', import.meta.url))
+  const offenders: string[] = []
+  const walk = (dir: string) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = dir + e.name
+      if (e.isDirectory()) walk(p + '/')
+      else if (e.name.endsWith('.ts') && e.name !== 'log.ts') {
+        const src = readFileSync(p, 'utf-8')
+        for (const m of src.matchAll(/console\.(log|warn|error)\(/g)) offenders.push(`${p.slice(root.length)}  console.${m[1]}`)
+      }
+    }
+  }
+  walk(root)
+  assert.deepEqual(offenders, [], `시각 없는 로그가 남아 있다 — twinLog·twinWarn·twinError 를 쓴다:\n  ${offenders.join('\n  ')}`)
+})

package/test/loop-lag.test.ts

@@ -0,0 +1,82 @@
+/*
+ * 루프 지체 계기 — **원인을 지어내지 않기 위한 값**이 정확한지 본다 (2026-08-21).
+ *
+ * 지키는 것:
+ *  ① 늦게 깨어난 만큼만 지체다 — 제때 깨어난 표본은 0 이고, 0 을 정체로 세지 않는다.
+ *  ② 창이 닫히기 전에는 `recent` 가 **null** 이다(채우는 중인 창을 「지금」으로 읽으면 과소 집계다).
+ *  ③ 가장 길게 막힌 **시각**을 든다 — 언제였는지가 원인을 가리는 근거다.
+ *  ④ 문턱 이하의 흔들림은 정체로 세지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { LoopLagSampler } from '../server/engine/loop-lag.ts'
+
+/** 시계를 손으로 밀어 넣는다 — 실제 타이머로 재면 기계 상태가 결과를 정한다. */
+function sampler(sampleMs = 500, stallMs = 200, windowMs = 10_000) {
+  let now = 1_000_000
+  const s = new LoopLagSampler(sampleMs, stallMs, windowMs, () => now)
+  return { s, advance: (ms: number) => (now += ms), at: () => now }
+}
+
+test('제때 깨어난 표본은 지체가 0 이고 정체로 세지 않는다', () => {
+  const { s, advance, at } = sampler()
+  for (let i = 0; i < 4; i++) {
+    advance(500)
+    assert.equal(s.sample(at()), 0)
+  }
+  assert.equal(s.view().total.stalls, 0)
+  assert.equal(s.view().total.maxMs, 0)
+  assert.equal(s.view().total.samples, 4)
+})
+
+test('늦게 깨어난 만큼이 지체다 — 그 초과분만', () => {
+  const { s, advance, at } = sampler()
+  advance(500)
+  s.sample(at())
+  advance(4_600) // 예정보다 4,100ms 늦게
+  assert.equal(s.sample(at()), 4_100)
+  assert.equal(s.view().total.maxMs, 4_100)
+  assert.equal(s.view().total.stalls, 1)
+})
+
+test('문턱 이하의 흔들림은 정체가 아니다 — 값은 남기고 세지는 않는다', () => {
+  const { s, advance, at } = sampler(500, 200)
+  advance(650) // 150ms 지체 — 문턱 200 미만
+  s.sample(at())
+  const v = s.view()
+  assert.equal(v.total.maxMs, 150)
+  assert.equal(v.total.stalls, 0, '문턱 이하를 세면 정상 상태가 정체로 보인다')
+})
+
+test('창이 닫히기 전에는 recent 가 null 이다 — 채우는 중인 창을 「지금」으로 읽지 않는다', () => {
+  const { s, advance, at } = sampler(500, 200, 2_000)
+  advance(500)
+  s.sample(at())
+  assert.equal(s.view().recent, null)
+
+  /* 창 길이를 넘기면 그 창이 닫혀 `recent` 가 된다. */
+  advance(2_000)
+  s.sample(at())
+  const v = s.view()
+  assert.ok(v.recent, '창 길이를 넘겼으면 닫힌 창이 있어야 한다')
+  assert.equal(v.recent!.stalls, 1, '1,500ms 지체는 정체 한 번이다')
+})
+
+test('가장 길게 막힌 시각을 든다 — 언제였는지가 원인을 가린다', () => {
+  const { s, advance, at } = sampler()
+  advance(500)
+  s.sample(at())
+  advance(3_000)
+  const worst = at()
+  s.sample(worst)
+  advance(500)
+  s.sample(at())
+  assert.equal(s.view().worstAtMs, worst)
+})
+
+test('한 번도 재지 않았으면 정체 시각은 null 이다 — 0 으로 적지 않는다', () => {
+  const { s } = sampler()
+  assert.equal(s.view().worstAtMs, null)
+  assert.equal(s.view().recent, null)
+})

package/test/model-gap.test.ts

@@ -0,0 +1,153 @@
+/*
+ * ★ 「원본이 말한 적 없는 것」을 세는 규율.
+ *
+ * ── 왜 이것이 필요한가 (2026-08-20 실측) ────────────────────────────────────
+ * 동기화 건강 기능을 만들 때 제가 전제를 이렇게 적었다: *「커넥터의 매핑이 한 글자 틀리면 트윈은
+ * 빈 공장이 된다」*. 사용자가 그 전제를 검증하게 해서 재 봤더니, 유입 문은 참조 오류를 **거부하지
+ * 않았다**:
+ *
+ *   모르는 로케이션 「오타-99」     → 통과
+ *   모르는 bizStep 「PUTAWAY_X17」 → 통과
+ *   모르는 계량기 「MMXU-오타-99」  → 통과
+ *
+ * 즉 그 기능이 잡겠다고 내세운 대표 사례가 `mapping-blocked` 로는 **뜰 수 없었다.** 거부되는 것은
+ * 형태 오류뿐이다(시각 형식·숫자 아닌 값·epc 없음).
+ *
+ * 거부하지 않는 것이 옳다 — 원천이 모델보다 먼저 새 로케이션을 말하는 것은 정상이고, 거부하면 그 선행
+ * 계측을 잃는다. 커널은 흡수하고 **표시한다**(`origin: 'observed'`). 빠져 있던 것은 그 표시를
+ * 「맞춰지고 있나」를 보는 사람에게 잇는 일이었다.
+ *
+ * ── 지키는 것 ───────────────────────────────────────────────────────────────
+ * ① 마스터가 말한 것과 관측으로 알게 된 것을 섞지 않는다
+ * ② 트윈이 안 돌면 `null` — 「없다」와 「세어 보지 못했다」는 다르다
+ * ③ 조용히 자르지 않는다 — 상한에서 밀려난 수를 함께 낸다
+ * ④ 덮지 못하는 축을 밝힌다 — 계량기는 커널이 표시를 달지 않아 이 화면이 못 찾아 준다
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { GAP_ID_LIMIT, modelGapOf } from '../server/engine/model-gap.ts'
+
+const loc = (id: string, origin: string) => ({ id, origin })
+
+test('마스터가 말한 로케이션은 갭이 아니다 — 선언된 것을 문제로 세지 않는다', () => {
+  const g = modelGapOf({
+    locations: [loc('dock-recv', 'master'), loc('bin-1', 'master')],
+    equipment: [loc('fk-1', 'master')]
+  })
+
+  assert.equal(g!.total, 0)
+  assert.deepEqual(g!.locations.ids, [])
+})
+
+test('관측으로만 알게 된 것을 축마다 센다 — 원천이 우리가 모르는 id 를 보내고 있다', () => {
+  const g = modelGapOf({
+    locations: [loc('dock-recv', 'master'), loc('오타-99', 'observed'), loc('A-77', 'observed')],
+    equipment: [loc('fk-1', 'master'), loc('없는-지게차', 'observed')],
+    persons: [loc('unknown-op', 'observed')]
+  })
+
+  assert.equal(g!.locations.count, 2)
+  assert.equal(g!.locations.unknown, 0, '표시가 다 있으면 모름은 0')
+  assert.deepEqual(g!.locations.ids, ['오타-99', 'A-77'], 'id 를 보여 준다 — 오타는 눈으로 찾는다')
+  assert.equal(g!.equipment.count, 1)
+  assert.equal(g!.persons.count, 1)
+  assert.equal(g!.total, 4, '세 축의 합')
+})
+
+test('트윈이 안 돌면 「없음」이다 — 0 이 아니다', () => {
+  /* 비교할 상대가 없다. 0 으로 답하면 「원천이 우리가 아는 것만 보낸다」는 없는 사실이 생긴다. */
+  assert.equal(modelGapOf(null), null)
+  assert.equal(modelGapOf(undefined), null)
+})
+
+test('돌지만 관측 갭이 없으면 0 이다 — 이건 「없음」과 다르다', () => {
+  const g = modelGapOf({ locations: [] })
+
+  assert.notEqual(g, null, '세어 봤다')
+  assert.equal(g!.total, 0, '세어 보니 없었다')
+})
+
+test('id 를 조용히 자르지 않는다 — 밀려난 수를 함께 낸다', () => {
+  const many = Array.from({ length: GAP_ID_LIMIT + 7 }, (_, i) => loc(`ghost-${i}`, 'observed'))
+  const g = modelGapOf({ locations: many })
+
+  assert.equal(g!.locations.count, GAP_ID_LIMIT + 7, '전부 센다')
+  assert.equal(g!.locations.ids.length, GAP_ID_LIMIT, '보이는 것은 상한까지')
+  assert.equal(g!.locations.more, 7, '밀려난 수를 말한다')
+})
+
+test('커널이 담을 줄 모른 사건을 함께 낸다 — 참조 문제와 다른 사실이다', () => {
+  const at = Date.parse('2026-08-20T01:02:03.000Z')
+  const g = modelGapOf({
+    unhandled: [
+      { eventType: 'epcis.TransformationEvent', count: 12, lastAtMs: at },
+      { eventType: 'aggregation-mixed-classes', count: 3 }
+    ]
+  })
+
+  assert.equal(g!.unhandled.length, 2)
+  assert.equal(g!.unhandled[0].lastAt, '2026-08-20T01:02:03.000Z', '언제까지 났는지 — 멈춘 종류는 고쳐진 것이다')
+  assert.equal(g!.unhandled[1].lastAt, null, '시각이 없으면 지어내지 않는다')
+})
+
+test('모르는 설비의 에너지 보고는 「없음」과 0 을 가른다 — 경로가 `energy` 안이다', () => {
+  /*
+   * 이 값을 **루트에서 읽고 있었다**(2026-08-20에 잡음). 커널은 `EnergyState` 안에 담으므로 루트에서
+   * 읽으면 영원히 `null` 이고, 오류 없이 「에너지 트윈이 아니다」로 읽힌다. 나만 읽는 필드를 잘못된
+   * 경로에서 읽으면 이렇게 조용히 사라진다.
+   *
+   * 그리고 커널은 0 이면 그 칸을 만들지 않는다. 그래서 `energy` 자체가 있는지로 「세었고 0」과
+   * 「에너지 트윈이 아님」을 가른다.
+   */
+  assert.equal(modelGapOf({})!.unknownEquipmentReports, null, '에너지 트윈이 아니면 이 수가 없다')
+  assert.equal(modelGapOf({ energy: { points: [] } })!.unknownEquipmentReports, 0, '에너지 트윈이면 세었고 0 이다')
+  assert.equal(modelGapOf({ energy: { unknownEquipment: 41 } })!.unknownEquipmentReports, 41)
+  assert.equal(
+    modelGapOf({ unknownEquipment: 41 } as any)!.unknownEquipmentReports,
+    null,
+    '루트에 있는 값을 집지 않는다 — 그 경로는 커널의 것이 아니다'
+  )
+})
+
+test('계량기도 덮는다 — 이 축이 가장 무겁다', () => {
+  /*
+   * 모르는 `meterId` 는 조용히 새 계량기가 되고 그 kW 가 그 현장의 수요·피크·요금 판정에 더해진다.
+   * 로케이션 오타는 스키매틱이 비는 것으로 드러나지만, 이건 **그럴듯한 숫자**로 나온다.
+   * 커널 0.7.39 가 `MeterPointState.origin` 을 내면서 덮을 수 있게 됐다.
+   */
+  const g = modelGapOf({
+    energy: { points: [loc('main-incoming', 'master'), loc('MMXU-오타-99', 'observed')] }
+  })
+
+  assert.equal(g!.meters.count, 1)
+  assert.deepEqual(g!.meters.ids, ['MMXU-오타-99'])
+  assert.equal(g!.total, 1, '계량기도 합에 든다')
+  assert.deepEqual(g!.notCovered, [], '덮지 못하는 축이 없다')
+})
+
+test('표시가 없는 항목은 「선언됨」이 아니라 「모름」으로 센다', () => {
+  /*
+   * 계량기의 `origin` 은 늦게 생긴 칸이라, 옛 스냅샷에서 이어받은 지점에는 없다(`undefined`).
+   * 마스터로 세면 오타를 놓치고, 관측으로 세면 정상을 문제로 만든다. 둘 다 틀리다.
+   */
+  const g = modelGapOf({
+    energy: { points: [{ id: 'carried-over' }, loc('main', 'master'), loc('ghost', 'observed')] }
+  })
+
+  assert.equal(g!.meters.unknown, 1, '표시 없는 것은 모름')
+  assert.equal(g!.meters.count, 1, '관측 갭에 섞이지 않는다')
+  assert.ok(!g!.meters.ids.includes('carried-over'), '모르는 것을 오타로 지목하지 않는다')
+})
+
+test('`origin` 은 「지금 모델에 있는가」의 답이다 — 채택되면 갭에서 빠진다', () => {
+  /*
+   * 커널이 표본마다 다시 맞춘다. 한 번 찍고 두면 나중에 선언된 계량기가 영원히 `observed` 로 남는다.
+   * 그래서 채택 뒤 스냅샷에서는 같은 id 가 `master` 로 오고, 이 도출은 그것을 그대로 따른다.
+   */
+  const before = modelGapOf({ energy: { points: [loc('new-meter', 'observed')] } })
+  const after = modelGapOf({ energy: { points: [loc('new-meter', 'master')] } })
+
+  assert.equal(before!.meters.count, 1)
+  assert.equal(after!.meters.count, 0, '모델에 들어오면 갭이 아니다')
+})

package/test/oee-accumulator.test.ts

@@ -18,6 +18,10 @@ const TICK = 1000
 function runSimCollect() {
   const m = {
     source: 'oee', system: 'wms' as const, siteName: 'O',
+  /* 이 픽스처가 식별자를 만드는 이름공간 — **픽스처마다 다르게** 둔다(같은 접두 아래에서 서로 다른
+     시험의 번호가 부딪치면 표준의 유일성 요구를 깬다, CBV 2.0 §8.2.4). 커널은 선언 없이 팔레트·문서를
+     만들지 않는다(0.7.45 에서 날조 프리픽스를 지웠다). */
+    identity: { namespaces: ['https://twin.test/oee-accumulator'] },
     space: { width: 90, depth: 40, unit: 'm' },
     locations: [
       { id: 'a', type: 'warehouse', role: 'area' as const },

package/test/operational-vocabulary.test.ts

@@ -37,7 +37,7 @@ test('운영 사실이 자기 봉투로 나온다 — EPCIS 로 감싸지지 않
 test('네 어휘가 한 배치에서 갈린다 — 실 피드는 섞여 온다', () => {
   const { accepted, rejected } = ingestCanonicalRecords(
     [
-      { epc: 'urn:epc:id:sgtin:1.1.1', action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:receiving', readPoint: 'dock-1' },
+      { epc: 'urn:epc:id:sgtin:9521321.012345.1', action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:receiving', readPoint: 'dock-1' },
       { meterId: 'm-1', kW: 120 },
       { equipmentId: 'pv-1', generatedKW: 40 },
       { moverId: 'fk-1', kind: 'forklift', status: 'busy' }, // vocabulary-guard: allow 저널 와이어 필드
@@ -80,8 +80,8 @@ test('피드 결선이 거부를 조용히 버리지 않는다 — 이유를 사
 test('담김 레코드가 자기 봉투로 나온다 — 개체 관측과 한 배치에 섞여 와도 갈린다', () => {
   const { accepted, rejected } = ingestCanonicalRecords(
     [
-      { epc: 'urn:epc:id:sgtin:1.1.1', action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:receiving', readPoint: 'dock-1' },
-      { parentID: 'urn:epc:id:sscc:0614141.0000000001', childEPCs: ['urn:epc:id:sgtin:1.1.1'], action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:packing', readPoint: 'packing' }
+      { epc: 'urn:epc:id:sgtin:9521321.012345.1', action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:receiving', readPoint: 'dock-1' },
+      { parentID: 'urn:epc:id:sscc:0614141.0000000001', childEPCs: ['urn:epc:id:sgtin:9521321.012345.1'], action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:packing', readPoint: 'packing' }
     ] as any,
     'domain-1',
     AT
@@ -93,7 +93,7 @@ test('담김 레코드가 자기 봉투로 나온다 — 개체 관측과 한
 
 test('자리를 구조째 실으면 거부한다 — 예전에는 "[object Object]" 로 굳어 저널에 쌓였다', () => {
   const { accepted, rejected } = ingestCanonicalRecords(
-    [{ epc: 'urn:epc:id:sgtin:1.1.1', action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:receiving', readPoint: { id: 'dock-1' } }] as any,
+    [{ epc: 'urn:epc:id:sgtin:9521321.012345.1', action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:receiving', readPoint: { id: 'dock-1' } }] as any,
     'domain-1',
     AT
   )

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

@@ -0,0 +1,145 @@
+/*
+ * ★ 「원본에 닿지 못한다」와 「원본이 조용하다」는 **다른 사실**이다 — 상태가 그것을 가려야 한다.
+ *
+ * ── 무엇이 조용했나 (2026-08-23 실측) ───────────────────────────────────────
+ * 실 원본이 끊겼다(`jejoup.hatiolab.com:4000` 접속 시간 초과, HTTP 000 / 8초). 그런데 트윈의
+ * **조회 가능한 상태 어디에도 그 사실이 없었다.**
+ *
+ *   recordIngest        `onRecords` 가 불릴 때만 도달한다 — 읽기 실패는 그 문에 오지 않는다
+ *   TwinReference.lastError  마스터 동기·접속 시험에만 적힌다 — 라이브 피드는 적지 않았다
+ *   계약                `openLiveFeed` 에 「읽지 못했다」를 말할 통로가 없었다
+ *
+ * 어댑터는 **로그로는 말하고 있었다**(재시도 경고). 그러나 로그는 사람이 볼 때만 값이 있다 — 화면이
+ * 말하려면 상태에 있어야 한다. 실증 데모 중에 원본이 끊기면 사용자가 원인을 찾을 수 없다.
+ *
+ * ── 이 시험이 지키는 것 ─────────────────────────────────────────────────────
+ * ① 실패가 상태에 남는다  ② 「몇 번」과 「언제부터」를 함께 든다(한 번의 흔들림과 20분째 단절은 다르다)
+ * ③ **빈 읽기는 성공이다** — 조용한 원본을 끊긴 원본으로 만들지 않는다
+ * ④ 조회 뷰로 나간다 — 상태에만 있고 안 나가면 화면이 못 본다
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  clearReadFailure,
+  ingestHealth,
+  newIngestLedger,
+  recordIngest,
+  recordReadFailure
+} from '../server/engine/ingest-health.ts'
+
+const T0 = Date.parse('2026-08-23T06:00:00.000Z')
+
+test('실패가 상태에 남는다 — 사유와 흐름까지', () => {
+  const l = newIngestLedger()
+  assert.equal(l.readFailure, undefined, '처음에는 없다(없음이 「닿는다」는 뜻이다)')
+  recordReadFailure(l, 'connect ETIMEDOUT', T0, 'lot')
+  assert.equal(l.readFailure?.consecutive, 1)
+  assert.equal(l.readFailure?.reason, 'connect ETIMEDOUT')
+  assert.equal(l.readFailure?.stream, 'lot', '어느 표가 막혔나가 원인 찾기의 절반이다')
+})
+
+test('한 번의 흔들림과 20분째 단절을 가른다 — 시작 시각을 지킨다', () => {
+  /*
+   * 매번 새로 적으면 화면이 늘 「방금 실패했다」만 보게 되고, 계속된 단절을 대수롭지 않게 말한다.
+   */
+  const l = newIngestLedger()
+  recordReadFailure(l, 'ETIMEDOUT', T0)
+  recordReadFailure(l, 'ETIMEDOUT', T0 + 600_000)
+  recordReadFailure(l, 'ETIMEDOUT', T0 + 1_200_000)
+  assert.equal(l.readFailure?.consecutive, 3)
+  assert.equal(l.readFailure?.sinceMs, T0, '처음 실패한 시각을 지킨다')
+  assert.equal(l.readFailure?.lastAtMs, T0 + 1_200_000, '마지막 실패는 갱신된다')
+})
+
+test('빈 읽기는 성공이다 — 조용한 원본을 끊긴 원본으로 만들지 않는다', () => {
+  /*
+   * ★ 이 단정이 고치려던 것의 **반대 방향으로 틀리는 것**을 막는다. 원본이 「새 것이 없다」고 답한 것은
+   * 닿았다는 뜻이다.
+   */
+  const l = newIngestLedger()
+  recordReadFailure(l, 'ETIMEDOUT', T0)
+  clearReadFailure(l)
+  assert.equal(l.readFailure, undefined, '읽었으면 단절 기록이 사라진다')
+  /* 그리고 그 뒤 다시 실패하면 **새 단절**이다 — 옛 시작 시각을 물려받지 않는다. */
+  recordReadFailure(l, 'ETIMEDOUT', T0 + 3_600_000)
+  assert.equal(l.readFailure?.consecutive, 1, '연속이 끊겼으므로 1 부터')
+  assert.equal(l.readFailure?.sinceMs, T0 + 3_600_000, '새 단절의 시작이다')
+})
+
+test('조회 뷰로 나간다 — 상태에만 있으면 화면이 못 본다', () => {
+  const l = newIngestLedger()
+  recordReadFailure(l, 'connect ETIMEDOUT', T0, 'inventory')
+  const v = ingestHealth(l, 'attached', undefined, T0 + 60_000)
+  assert.ok(v.readFailure, '뷰에 실려야 한다')
+  assert.equal(v.readFailure?.consecutive, 1)
+  assert.equal(v.readFailure?.since, new Date(T0).toISOString())
+  assert.equal(v.readFailure?.reason, 'connect ETIMEDOUT')
+  assert.equal(v.readFailure?.stream, 'inventory')
+})
+
+test('닿고 있으면 그 필드를 만들지 않는다 — 빈 값이 「닿는다」로 읽히지 않게', () => {
+  const l = newIngestLedger()
+  recordIngest(l, 3, [], T0)
+  const v = ingestHealth(l, 'attached', undefined, T0 + 1000)
+  assert.equal(v.readFailure, undefined)
+  /* 가드가 스스로를 증명한다 — 이 장부가 실제로 무엇을 받았다. */
+  assert.equal(v.total.offered, 3, '빈 비교로 통과하지 않는다')
+})
+
+test('「유입 없음」과 「닿지 못함」은 다른 판정이다', () => {
+  /*
+   * 유입 없음은 원본이 조용한 것일 수 있고, 닿지 못함은 우리가 묻지도 못한 것이다. 두 상태가 같은
+   * 값으로 뭉개지면 화면이 두 문장을 다르게 말할 수 없다.
+   */
+  const quiet = newIngestLedger()
+  const dark = newIngestLedger()
+  recordReadFailure(dark, 'ETIMEDOUT', T0)
+
+  const vq = ingestHealth(quiet, 'attached', undefined, T0)
+  const vd = ingestHealth(dark, 'attached', undefined, T0)
+  assert.equal(vq.lastAt, null, '조용한 쪽도 받은 것이 없다')
+  assert.equal(vd.lastAt, null, '끊긴 쪽도 받은 것이 없다 — 그 값만으로는 갈리지 않는다')
+  assert.notEqual(Boolean(vq.readFailure), Boolean(vd.readFailure), '이 축이 그 둘을 가른다')
+})
+
+/*
+ * ── 읽기 실패가 **피드를 끄면 안 된다** (2026-08-23, 되돌린 자리) ────────────
+ *
+ * 처음 구현에서 읽기 실패가 레퍼런스 행의 `status` 를 `'error'` 로 적었다. 그것이 **피드를 영구히
+ * 껐다**: 부팅 재부착은 `status: 'connected'` 인 레퍼런스만 되살리므로, 원본이 **잠깐** 끊긴 것이
+ * 다음 재기동에서 그 트윈을 아예 굶겼다. 실측으로 그렇게 났다 — 그 판의 로그에 `[twin-live]` 줄이
+ * 한 줄도 없었다.
+ *
+ * 두 축을 한 칸에 섞은 것이 원인이다.
+ *
+ *   status      **연결 설정이 성립하나** — 접속 시험·마스터 동기가 정한다. 재부착의 **자격**이다
+ *   읽기 실패    **지금 닿나** — 오갈 수 있는 사실이고 유입 장부가 그 축을 갖는다
+ *
+ * 「사실을 말하게」 하려던 것이 「사실을 못 듣게」 만들었다. 그 방향의 실패는 조용하다 — 화면은
+ * 「원본에 닿지 못한다」를 정직하게 말하면서, 정작 다시 닿을 기회를 잃는다.
+ */
+test('읽기 실패가 레퍼런스의 status 를 건드리지 않는다 — 그것이 재부착의 자격이다', () => {
+  const src = readFileSync(join(import.meta.dirname, '..', 'server', 'service', 'reference', 'reference-live.ts'), 'utf8')
+  const code = src.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/(^|[^:])\/\/.*$/gm, '$1')
+
+  const at = code.indexOf('onReadFailure:')
+  assert.ok(at > 0, 'onReadFailure 배선이 있어야 한다')
+  const body = code.slice(at, at + 600)
+
+  assert.doesNotMatch(body, /status:/, '읽기 실패는 status 를 적지 않는다 — 적으면 다음 부팅이 그 피드를 되살리지 않는다')
+  /* 대신 이유는 남긴다 — 사람이 목록에서 볼 수 있게. */
+  assert.match(body, /lastError/, '이유는 레퍼런스 행에 남긴다')
+  /* 그리고 「지금 닿나」는 장부가 답한다. */
+  assert.match(body, /recordIngestReadFailure/, '유입 장부가 그 축을 든다')
+})
+
+test('재부착의 자격은 connected 뿐이다 — 그래서 그 값을 함부로 바꾸면 안 된다', () => {
+  /*
+   * 이 단정이 위 가드의 **이유**를 못박는다. 재부착 조건이 넓어지면 위 규율의 근거가 약해지므로,
+   * 둘이 함께 움직여야 한다.
+   */
+  const src = readFileSync(join(import.meta.dirname, '..', 'server', 'service', 'reference', 'reference-live.ts'), 'utf8')
+  assert.match(src, /find\(\{ where: \{ status: 'connected' \}/, '부팅 재부착은 connected 만 되살린다')
+})

package/test/reference-grounding.test.ts

@@ -0,0 +1,70 @@
+/*
+ * ★ 커넥터의 **근거 수준** — 목으로 확인한 것을 확인으로 부르지 않는다.
+ *
+ * ── 왜 이 축이 생겼나 (2026-08-23, 토대 릴리즈 준비) ────────────────────────
+ * 등록된 커넥터 열넷 중 실 시스템에 붙어 본 것은 **하나**다(첫 실 연동). 나머지는 목에 대고 만들었다.
+ * 그런데 화면의 커넥터 목록에 그 구분이 없어서 **목으로 확인한 것이 확인으로 보인다.**
+ *
+ * 이 저장소는 같은 모양을 능력 축에서 이미 거절했다 — 「선언만 있는 능력은 사용자에게 거짓말이 된다」
+ * (§`capabilitiesOf`). 그 규율을 근거에도 세운다.
+ *
+ * ── 무엇을 검증할 수 있고 무엇을 못 하나 ────────────────────────────────────
+ * 능력은 구현이 있는지 보아 선언을 검증할 수 있다. **근거는 볼 수 없다** — 사람이 아는 사실이다.
+ * 그래서 검증할 수 있는 하나만 검증한다: **실 시스템을 주장하면 무엇에 대고인지 말해야 한다.**
+ * 가리키는 대상이 없는 주장은 주장이 아니고, 그런 주장은 낡아도 아무도 알 수 없다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { groundingOf, type ReferenceAdapter } from '../server/service/reference/reference-adapter.ts'
+
+const adapter = (grounding?: any) => ({ type: 't', grounding } as unknown as ReferenceAdapter)
+
+test('선언이 없으면 「모른다」다 — 「목이다」가 아니다', () => {
+  /*
+   * 둘을 같게 두면 아직 선언하지 않은 새 커넥터가 목으로 낙인찍힌다 — 그것도 없는 사실이다.
+   * 화면은 `unknown` 을 「아직 밝히지 않았다」로 말해야 한다.
+   */
+  assert.deepEqual(groundingOf(adapter()), { level: 'unknown' })
+  assert.deepEqual(groundingOf(undefined), { level: 'unknown' })
+})
+
+test('실 시스템을 주장하면 무엇에 대고인지 말해야 한다 — 아니면 주장이 내려간다', () => {
+  /* ★ 이 가드의 핵심. 대상 없는 주장은 낡아도 아무도 모른다. */
+  for (const level of ['instance', 'product'] as const) {
+    const g = groundingOf(adapter({ level }))
+    assert.equal(g.level, 'unknown', `${level} 주장이 대상 없이 통과하면 안 된다`)
+    assert.match(g.downgraded ?? '', /does not say what it was verified against/)
+    assert.match(g.downgraded ?? '', new RegExp(level), '무엇을 주장했는지 함께 말한다')
+  }
+  /* 여백만 있는 것도 비어 있는 것이다 — 형식을 채워 통과하지 못하게. */
+  assert.equal(groundingOf(adapter({ level: 'instance', verifiedAgainst: '   ' })).level, 'unknown')
+})
+
+test('대상을 말하면 그 주장이 선다', () => {
+  const g = groundingOf(adapter({ level: 'instance', verifiedAgainst: 'chef v1 · jejoup / pocheon' }))
+  assert.equal(g.level, 'instance')
+  assert.equal(g.verifiedAgainst, 'chef v1 · jejoup / pocheon')
+  assert.equal(g.downgraded, undefined)
+})
+
+test('목과 가상은 대상 없이도 선다 — 그 자체가 사실이다', () => {
+  /*
+   * `mock` 은 「실 시스템에 붙어 본 적이 없다」는 사실이고 그것을 말하는 데 대상이 필요하지 않다.
+   * `synthetic` 은 한계가 아니라 **성질**이다 — 가상 원본은 스스로 만들어 낸다.
+   */
+  assert.equal(groundingOf(adapter({ level: 'mock' })).level, 'mock')
+  assert.equal(groundingOf(adapter({ level: 'synthetic' })).level, 'synthetic')
+})
+
+test('instance 와 product 를 가른다 — 그 구분이 이 어휘의 요점이다', () => {
+  /*
+   * 첫 실 연동에서 그 배포만의 성질이 넷 드러났는데(관계 리솔버가 다른 테넌트의 행을 답한다 · 모르는
+   * 필터를 조용히 무시한다 · 지워진 품목의 BOM 이 남아 있다 · 사실상 무한을 뜻하는 표식) **그것이
+   * 제품의 성질인지 그 인스턴스의 성질인지 아무도 모른다.** 두 번째 배포가 붙는 날 갈린다.
+   *
+   * 그래서 하나로 확인한 것을 `product` 라 부르면 안 되고, 어휘가 그 구분을 담는다.
+   */
+  const one = groundingOf(adapter({ level: 'instance', verifiedAgainst: '한 배포' }))
+  const many = groundingOf(adapter({ level: 'product', verifiedAgainst: '세 배포' }))
+  assert.notEqual(one.level, many.level, '두 수준이 같은 값으로 뭉개지지 않는다')
+})

package/test/resolve-ts-siblings.mjs

@@ -0,0 +1,52 @@
+/*
+ * ★ 소스 시험이 형제 모듈을 부를 수 있게 한다 — **`operato-twin` 의 같은 규칙을 이 패키지에도 둔다** — **`.js` 로 적힌 상대 경로를 `.ts` 로 되짚는다.**
+ *
+ * ── 무엇이 서고 있었나 (2026-08-22) ─────────────────────────────────────────
+ * 이 패키지의 `npm test` 는 `node --test test/*.test.ts` 로 **소스를 그대로 실행**한다. 그런데 서버
+ * 소스는 tsc 로 빌드되는 코드이므로 상대 import 를 `'./x.js'` 로 적는다(그것이 빌드 산출물에서 맞는
+ * 경로다). 타입만 지우는 실행은 그 `.js` 를 `.ts` 로 바꿔 주지 않는다.
+ *
+ * 그래서 **소스 모듈이 형제 모듈을 값으로 참조하는 순간** 그 모듈 그래프를 부르는 시험이 전부 선다.
+ * 실측으로 하루에 네 종류가 이 벽에 걸렸다: `identity/namespace.js`(정체성 이름공간) ·
+ * `engine/log.js`(로그 문) · `isa95-coverage.js`(적합성 판정) · `journal-count.js`(저널 세기). 늘 같은 오류다.
+ *
+ *   Cannot find module '…/server/identity/namespace.js' imported from '…/templates/wms-unit-load.ts'
+ *
+ * ── 왜 이 방식인가 ──────────────────────────────────────────────────────────
+ * 고르던 길이 둘 있었다.
+ *
+ *  ① 그 시험들을 **빌드 산출물**(`dist-server`)로 돌린다 — 이 패키지에 전례가 있다. 그러나 시험마다
+ *     그 배선을 적어야 하고, 걸리는 시험이 늘 때마다 같은 일을 다시 한다. 그리고 산출물이 낡으면
+ *     **고친 코드가 아닌 것이 돌면서 초록으로 보인다.**
+ *  ② 상수를 쓰는 파일 안으로 옮긴다 — 값 참조가 사라지지만 **정본이 흩어진다.** 그것이 이 상수를 한
+ *     자리에 모은 이유와 정면으로 어긋난다.
+ *
+ * 둘 다 증상을 피하는 것이고, 원인은 **해석 규칙 하나**다. 그래서 규칙을 고친다: 상대 경로 `.js` 가
+ * 없고 같은 이름의 `.ts` 가 있으면 그것을 쓴다. 한 자리에 두므로 걸리는 시험이 늘어도 할 일이 없다.
+ *
+ * ── 무엇을 하지 않는가 ─────────────────────────────────────────────────────
+ * **패키지 이름(`@things-factory/…`)은 손대지 않는다.** 그것은 의존 패키지의 산출물을 가리키는
+ * 것이고 실제로 `.js` 가 있다. 되짚는 것은 **상대 경로**뿐이고, 그것도 `.ts` 가 실제로 있을 때만이다 —
+ * 없으면 원래 오류가 그대로 난다(없는 것을 지어내지 않는다).
+ */
+import { registerHooks } from 'node:module'
+import { existsSync } from 'node:fs'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+registerHooks({
+  resolve(specifier, context, nextResolve) {
+    /* 상대 경로의 `.js` 만 본다 — 패키지 이름과 그 밖의 확장자는 그대로 둔다. */
+    if (!specifier.startsWith('.') || !specifier.endsWith('.js')) return nextResolve(specifier, context)
+
+    try {
+      return nextResolve(specifier, context)
+    } catch (err) {
+      /* 해석이 실패한 그때만 `.ts` 를 본다 — 성공하는 경로의 뜻을 바꾸지 않는다. */
+      const parent = context?.parentURL
+      if (!parent) throw err
+      const asTs = new URL(specifier.slice(0, -3) + '.ts', parent)
+      if (!existsSync(fileURLToPath(asTs))) throw err
+      return { url: pathToFileURL(fileURLToPath(asTs)).href, shortCircuit: true, format: 'module-typescript' }
+    }
+  }
+})