@things-factory/headless-twin 10.0.11 → 10.0.13

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/operation-basis.test.ts

@@ -93,8 +93,35 @@ test('이력 목록은 선언 대조에도 쓰인다 — 오타를 그때부터
  */
 test('시뮬 기동이 모드를 적는다 — 「돌고 있나」를 묻는 쪽이 답을 받아야 한다', () => {
   const src = readFileSync(fileURLToPath(new URL('../server/engine/twin-engine.ts', import.meta.url)), 'utf-8')
-  assert.match(src, /id, domainId, mode: 'sim', runtime/, '시뮬 런타임도 모드를 든다')
+  assert.match(src, /mode: 'sim',\s*\n\s*runtime/, '시뮬 런타임도 모드를 든다')
   /* 답이 갈리는 자리 — 도는 트윈이면 「재기동 때 받는다」로 말해야 한다. */
   const mut = readFileSync(fileURLToPath(new URL('../server/service/twin-model/twin-model-mutation.ts', import.meta.url)), 'utf-8')
   assert.match(mut, /running \? 'on-restart' : 'stored'/)
 })
+
+/*
+ * ── 공정 모수도 목록에 실린다 (2026-08-19) ──────────────────────────────────
+ * 수율·셋업은 시간과 다른 표에 담긴다(`localParams`). 목록이 그것을 함께 들지 않으면 선언해 둔 값이
+ * 화면에서 사라지고, 그러면 철회할 자리도 없어진다. 원천이 말한 모수도 함께 들어 견줄 수 있게 한다.
+ */
+test('선언한 모수와 원천 모수를 함께 든다 — 무엇을 고쳤나가 보인다', () => {
+  const model = {
+    operations: [{ key: 'weld', label: 'Welding', intent: 'process', parameters: [{ id: 'yield', value: '0.7' }] }],
+    localParams: { weld: { yield: '0.92', setupDuration: 'PT30S' } }
+  }
+  const rows = operationBasis(model, kernelReporting([{ kind: 'weld', duration: 'declared' }]))
+  assert.deepEqual(rows, [
+    {
+      kind: 'weld',
+      label: 'Welding',
+      referenceParams: { yield: '0.7' },
+      basis: 'declared',
+      localParams: { yield: '0.92', setupDuration: 'PT30S' }
+    }
+  ])
+})
+
+test('모수만 선언한 공정도 목록에 남는다 — 커널이 아직 돌리지 않았어도', () => {
+  const rows = operationBasis({ localParams: { inspect: { yield: '0.99' } } }, undefined)
+  assert.deepEqual(rows, [{ kind: 'inspect', localParams: { yield: '0.99' } }])
+})

package/test/operational-vocabulary.test.ts

@@ -0,0 +1,108 @@
+/*
+ * **라이브 문이 운영 사실을 안다** — 미러가 시뮬보다 가난하지 않게 (ADR-0029 어휘 넓히기, 2026-08-19).
+ *
+ * ── 무엇이 막혀 있었나 ──────────────────────────────────────────────────────
+ * 이 문(`ingestCanonicalRecords`)은 어휘를 셋만 알았다: EPCIS 품목 · 에너지 계량 · 설비 에너지. 그리고
+ * **모르는 것은 EPCIS 로 떨어졌다** — 작업 사실을 넣으면 `epc` 가 없어 거부됐고, 원본은 「이 작업이
+ * 끝났다」를 말할 길이 없었다. 시뮬 커널만 그것을 알고 미러는 영원히 몰랐다.
+ *
+ * ── 이 시험이 지키는 것 ─────────────────────────────────────────────────────
+ *  ① 네 어휘가 **한 문**에서 갈린다(판정은 커널의 것이고 여기서 다시 짐작하지 않는다).
+ *  ② 운영 사실이 자기 봉투로 나온다 — EPCIS 로 감싸지지 않는다.
+ *  ③ 섞여 와도 갈린다(실 피드는 한 배치에 여러 어휘가 섞인다).
+ *  ④ 거부는 이유와 함께 남는다 — 피드 결선이 그 이유를 사람에게 말한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { ingestCanonicalRecords } from '../server/engine/canonical-ingest.ts'
+
+const AT = '2026-08-19T09:00:00.000Z'
+
+test('운영 사실이 자기 봉투로 나온다 — EPCIS 로 감싸지지 않는다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(
+    [{ taskId: 'tk-1', kind: 'putaway', status: 'completed' } as any],
+    'domain-1',
+    AT
+  )
+  assert.deepEqual(rejected, [])
+  assert.equal(accepted.length, 1)
+  assert.equal(accepted[0].eventType, 'task.status')
+  assert.equal(accepted[0].eventTime, AT, '시각을 주지 않으면 이 문이 정한 기본 시각을 쓴다')
+  assert.equal(accepted[0].tenantId, 'domain-1')
+})
+
+test('네 어휘가 한 배치에서 갈린다 — 실 피드는 섞여 온다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(
+    [
+      { 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 저널 와이어 필드
+      { orderId: 'or-1', kind: 'outbound', status: 'picking', requested: 10, fulfilled: 3 }
+    ] as any,
+    'domain-1',
+    AT
+  )
+  assert.deepEqual(rejected, [], '어느 어휘도 남의 길로 떨어지지 않는다')
+  assert.deepEqual(accepted.map(e => e.eventType).sort(), [
+    'energy.equipment', 'energy.measured', 'epcis.ObjectEvent', 'equipment.status', 'order.status'
+  ].sort())
+})
+
+test('거부는 이유와 함께 남는다 — 유효한 것은 함께 통과한다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(
+    [
+      { taskId: 'tk-1', kind: 'pick', status: 'completed' },
+      { taskId: 'tk-2', kind: 'pick', status: 'FINISHED' } // 커널이 접을 수 없는 낱말
+    ] as any,
+    'domain-1',
+    AT
+  )
+  assert.equal(accepted.length, 1)
+  assert.equal(rejected.length, 1)
+  assert.ok(rejected[0].errors.join(' ').length > 0)
+})
+
+test('피드 결선이 거부를 조용히 버리지 않는다 — 이유를 사람에게 말한다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/service/reference/reference-live.ts', import.meta.url)), 'utf-8')
+  assert.match(src, /record\(s\) rejected/, '거부 수와 이유를 남긴다')
+})
+
+/*
+ * ── 담김도 이 문을 지난다 (2026-08-19) ──────────────────────────────────────
+ * 실 앱에서 한 바퀴 돌리자 「옮기지 못했다」 로그가 `epcis.AggregationEvent` 를 짚었다 — 관측 리듀서는 그
+ * 사실로 자식 물품에 `parent` 를 붙이는데(3D 가 「이 상자가 어느 팔레트에 실렸나」를 묻는 자리) 문에 그
+ * 어휘가 없었다.
+ */
+test('담김 레코드가 자기 봉투로 나온다 — 개체 관측과 한 배치에 섞여 와도 갈린다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(
+    [
+      { 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
+  )
+  assert.deepEqual(rejected, [])
+  assert.deepEqual(accepted.map(e => e.eventType), ['epcis.ObjectEvent', 'epcis.AggregationEvent'])
+  assert.equal((accepted[1].data as any).parentID, 'urn:epc:id:sscc:0614141.0000000001')
+})
+
+test('자리를 구조째 실으면 거부한다 — 예전에는 "[object Object]" 로 굳어 저널에 쌓였다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(
+    [{ 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
+  )
+  assert.equal(accepted.length, 0)
+  assert.match(rejected[0].errors.join(' '), /readPoint/)
+})
+
+test('이 문이 어휘가 넷임을 스스로 말한다 — 다음 사람이 세 어휘로 읽지 않게', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/engine/canonical-ingest.ts', import.meta.url)), 'utf-8')
+  assert.match(src, /어휘가 넷이다/)
+  assert.match(src, /isOperationalRecord/, '판정은 커널의 것을 부른다(여기서 다시 짐작하지 않는다)')
+})

package/test/operations-capability-db.test.ts

@@ -102,8 +102,8 @@ before(async () => {
   q = new TwinJournalQuery()
   ctx = { state: { domain: { id: domainId } } }
 
-  await TwinEngine.ingestMaster(domainId, mesMaster())
-  await TwinEngine.ingestMaster(domainId, wmsMaster())
+  await TwinEngine.ingestMaster(domainId, mesMaster(), 'reset')
+  await TwinEngine.ingestMaster(domainId, wmsMaster(), 'reset')
 })
 
 after(async () => {
@@ -122,7 +122,7 @@ test('실행 중이 아니면 그 사실을 알린다 — "없는 것" 과 구
 })
 
 test('돌고 있으면 구간의 양을 종류로 갈라 낸다 — 표준 등식이 성립한다', async () => {
-  await TwinEngine.startFromRegistry(domainId, MES, 'sim-experiment')
+  await TwinEngine.startFromRegistry(domainId, MES, 'reset')
   const rows = await ask(MES)
   assert.equal(rows[0].reason, undefined)
 
@@ -138,7 +138,7 @@ test('돌고 있으면 구간의 양을 종류로 갈라 낸다 — 표준 등
 })
 
 test('공정을 선언하지 않은 트윈은 판정 대상이 아니다 — 0 으로 채우면 없는 병목이 생긴다', async () => {
-  await TwinEngine.startFromRegistry(domainId, WMS, 'sim-experiment')
+  await TwinEngine.startFromRegistry(domainId, WMS, 'reset')
   const rows = await q.twinOperationsCapability(WMS, undefined, 24, WINDOW.fromTime, WINDOW.toTime, WINDOW.fromTime, ctx)
   assert.equal(rows[0].reason, 'no-operations')
   assert.equal(rows[0].report, undefined)

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

@@ -81,7 +81,7 @@ before(async () => {
     domain: { id: domainId },
     instanceId: INSTANCE,
     kind: 'mes',
-    realityMode: 'sim-experiment',
+    restartPolicy: 'reset',
     purpose: 'operational',
     status: 'stopped',
     model: {}

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

@@ -184,7 +184,7 @@ before(async () => {
   q = new TwinModelItemQuery()
   ctx = { state: { domain: { id: domainId } } }
 
-  await TwinEngine.ingestMaster(domainId, master())
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })
 
 after(async () => {

package/test/property-effects.test.ts

@@ -94,3 +94,31 @@ test('공정 시간이 등록돼 있고, 그 값을 실어 보내는 자리를
   assert.match(layer, /isoDurationOf/, '커널이 읽는 표기로 바꾼다')
   assert.match(hostSrc('engine/twin-engine.ts'), /declareDurations\(declared\)/, '기동·구조전환 때 커널에 싣는다')
 })
+
+/*
+ * 모수도 같은 배선을 지난다 (2026-08-19).
+ *
+ * 이 시험이 소스를 보는 이유: 모수를 읽는 순간은 **작업이 완료될 때**라서 실 앱에서 관측하려면 라인이
+ * 한 바퀴 돌아야 한다(복원된 25분 작업이 쌓인 트윈에서는 그 관측이 오래 걸린다 — 실제로 그랬다).
+ * 값이 커널까지 가는 **경로**는 여기서 지키고, 커널이 그 값을 쓰는지는 커널 시험이 값으로 지킨다.
+ */
+test('수율·셋업이 커널 창구까지 배선돼 있다 — 등록만 하고 나르지 않으면 화면이 거짓을 말한다', () => {
+  const layer = hostSrc('engine/local-declarations.ts')
+  assert.match(layer, /OPERATION_PROPERTY\.yield/, '선언 겹이 수율을 안다')
+  assert.match(layer, /OPERATION_PROPERTY\.setupDuration/, '선언 겹이 셋업을 안다')
+  /* 퍼센트 → 비율 환산은 **한 곳**이어야 한다(두 곳이면 100 이 두 번 걸린다). */
+  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/, '버전 어긋남을 경고로 드러낸다')
+})
+
+test('공정 모수가 등록부에 있고 읽는 자리를 가리킨다', () => {
+  for (const id of ['operation.yield', 'operation.setupDuration']) {
+    const e = PROPERTY_EFFECTS.find(x => x.id === id)!
+    assert.ok(e, `${id} 가 등록부에 있어야 한다`)
+    assert.deepEqual(e.axes, ['operations'])
+    assert.match(e.readBy, /declareParameters/, '어느 창구로 가는지 말한다')
+  }
+})

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, '두 수준이 같은 값으로 뭉개지지 않는다')
+})