@things-factory/headless-twin 10.0.12 → 10.0.13

package/test/canonical-quantity-door.test.ts

@@ -0,0 +1,61 @@
+/*
+ * ★ 비직렬 수량이 들어오는 문 — **조용히 사라지지 않는다.**
+ *
+ * `CanonicalRecord` 에 `quantityList` 자리를 냈다(담김의 `childQuantityList` 가 하루 먼저 같은 이유로
+ * 받은 자리다). 원본이 「이 자리에 이 품목이 얼마 남았다」를 말할 길이 없어서, 그것이 주된 경로인
+ * 시스템(식품 제조 MES)은 라이브를 낼 수 없었다.
+ *
+ * ── 배포 뒤 (2026-08-21) ────────────────────────────────────────────────────
+ * 커널 0.7.40 에 `ObjectEventMapping.quantityList` 가 들어와 **수량만 오는 레코드가 통과한다.**
+ * 그 전까지는 `epcList` 와 `quantityList` 가 둘 다 비어 검증이 거부했고, 이 시험은 그 거부가 **조용하지
+ * 않다**(이유와 함께 계수된다)는 것을 지켰다.
+ *
+ * 이제 통과 쪽으로 고정한다 — 통과와 거부를 둘 다 받아들이면 다시 막혔을 때 초록으로 남는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { ingestCanonicalRecords } from '../server/engine/canonical-ingest.ts'
+
+const T0 = '2026-08-20T09:00:00.000Z'
+const CLASS = 'https://chef.example.com/class/product-7f3a'
+
+const qtyRecord = {
+  action: 'OBSERVE',
+  bizStep: 'urn:epcglobal:cbv:bizstep:storing',
+  disposition: 'urn:epcglobal:cbv:disp:sellable_accessible',
+  quantityList: [{ epcClass: CLASS, quantity: 3.5, uom: 'KGM' }],
+  readPoint: 'chef-wh:w1',
+  bizLocation: 'chef-wh:w1'
+}
+
+test('수량만 오는 레코드가 통과하고 수량이 봉투까지 실린다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(qtyRecord as any, 'plantA', T0)
+  assert.deepEqual(rejected, [], `거부됐다 — 커널에 quantityList 자리가 있는지 확인: ${JSON.stringify(rejected)}`)
+  assert.equal(accepted.length, 1)
+  /* 자리만 통과하고 값이 빠지면 더 나쁘다 — 실린 줄 알고 잃는다. */
+  const ev: any = (accepted[0] as any).data ?? (accepted[0] as any).event ?? accepted[0]
+  assert.deepEqual(ev.quantityList, [{ epcClass: CLASS, quantity: 3.5, uom: 'KGM' }])
+  assert.deepEqual(ev.epcList, [], '개체가 없으므로 빈 배열이다 — 지어내지 않는다')
+})
+
+test('개체 관측은 그대로 통과한다 — 문을 내면서 기존 길을 막지 않는다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(
+    { epc: 'urn:epc:id:sgtin:9521321.012345.1', action: 'OBSERVE', bizStep: 'urn:epcglobal:cbv:bizstep:storing', readPoint: 'chef-wh:w1' } as any,
+    'plantA',
+    T0
+  )
+  assert.equal(rejected.length, 0, `개체 관측이 거부되면 안 된다: ${JSON.stringify(rejected)}`)
+  assert.equal(accepted.length, 1)
+})
+
+test('개체도 수량도 없으면 거부된다 — 무엇을 관측했는지 말하지 않았다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(
+    { action: 'OBSERVE', bizStep: 'urn:epcglobal:cbv:bizstep:storing', readPoint: 'chef-wh:w1' } as any,
+    'plantA',
+    T0
+  )
+  assert.equal(accepted.length, 0)
+  assert.equal(rejected.length, 1)
+  assert.ok(rejected[0].errors?.length, '이유 없이 버리지 않는다')
+})

package/test/command-routing.test.ts

@@ -43,7 +43,7 @@ test('없는 인스턴스와 다른 도메인은 같은 사유로 거절한다
   assert.deepEqual(routeCommand(sim, false, 'attention.ack'), { target: 'reject', errorCode: 'no-instance' })
 })
 
-test('런타임이 없는 시뮬 — 예외를 던지지 않고 이유를 알린다', () => {
+test('런타임이 없는 시뮬 — 오류를 내지 않고 이유를 알린다', () => {
   assert.deepEqual(routeCommand({ hasRuntime: false, hasKernelDispatch: true }, true, 'order.hold'), { target: 'reject', errorCode: 'no-runtime' })
 })
 

package/test/declared-location-types.test.ts

@@ -0,0 +1,89 @@
+/*
+ * ★ 자리 타입을 **누구에게 묻는가** — 원본이 선언했으면 그 선언이 정본이다.
+ *
+ * ── 무엇이 틀렸나 (2026-08-20) ──────────────────────────────────────────────
+ * 호스트는 「이 자리 타입을 아는가」를 **내장 카탈로그**에게만 물었다(`DOMAIN_CATALOG[system]`).
+ * 그런데 원본은 자기 `DomainDefinition.locationTypes` 를 함께 보낼 수 있고, 그러면 **그 선언이
+ * 정본**이다 — 카탈로그는 우리가 아는 도메인들의 기본 어휘일 뿐이다.
+ *
+ * 상대가 틀렸으니 결과가 이랬다: 자기 어휘를 선언한 원본(예: F&B 라인 — 배합·가열·세척·금속검출·
+ * 소분·포장)은 **정상적인 자리마다 경고를 하나씩** 받는다. 경고가 소음이 되면 사람은 그것을 읽지 않게
+ * 되고, 그때 **진짜 경고도 함께 죽는다.**
+ *
+ * ── 지키는 것 ───────────────────────────────────────────────────────────────
+ * ① 선언이 있으면 선언에 대조한다 ② 선언이 없으면 카탈로그로 떨어진다 ③ 선언을 **못 읽은 것**과
+ * 「아무것도 선언하지 않은 것」을 가른다(못 읽었으면 카탈로그로 떨어진다 — 빈 목록으로 읽으면 모든
+ * 자리가 경고를 받는다) ④ 아무 데도 없는 타입은 여전히 경고한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+
+const req = createRequire(import.meta.url)
+const { masterToTwin, declaredLocationTypes } = req('../dist-server/service/reference/reference-master.js')
+
+/** F&B 라인 — 내장 MES 카탈로그(트레일러 제조)에는 없는 어휘. */
+const FNB = ['mixing', 'cooking', 'washing', 'metal-detect', 'portioning', 'packing']
+
+const CATALOG = { mes: { locationTypes: ['raw-store', 'cut-station', 'fg-store'] } }
+
+const master = (types: string[], productionSpec?: unknown) => ({
+  source: 'chef-1',
+  system: 'mes',
+  siteName: '식품 공장',
+  /* `masterToTwin` 이 공간에서 spaceId 를 꺼낸다 — 최소 모양을 준다. */
+  space: { spaceId: 'chef-site', width: 60, depth: 30, unit: 'm' },
+  locations: types.map((t, i) => ({ id: `loc-${i}`, type: t, role: 'location' as const })),
+  equipment: [],
+  ...(productionSpec ? { productionSpec } : {})
+})
+
+const specWith = (keys: string[]) => ({ definition: { locationTypes: keys.map(k => ({ key: k, label: k })) } })
+
+const unknownWarnings = (r: any) => (r.warnings ?? []).filter((w: any) => w.code === 'unknown-location-type')
+
+test('원본이 선언했으면 그 선언에 대조한다 — 정상적인 자리에 경고를 주지 않는다', () => {
+  const r = masterToTwin(master(FNB, specWith(FNB)), CATALOG)
+
+  assert.deepEqual(unknownWarnings(r), [], 'F&B 여섯 자리 모두 선언돼 있다')
+})
+
+test('선언이 없으면 카탈로그로 떨어진다 — 예전 거동 그대로', () => {
+  const r = masterToTwin(master(['raw-store', 'mixing']), CATALOG)
+  const w = unknownWarnings(r)
+
+  assert.equal(w.length, 1, '카탈로그에 없는 하나만')
+  assert.equal(w[0].params.type, 'mixing')
+})
+
+test('선언에도 카탈로그에도 없으면 경고한다 — 진짜 경고는 죽이지 않는다', () => {
+  const r = masterToTwin(master([...FNB, 'ghost-station'], specWith(FNB)), CATALOG)
+  const w = unknownWarnings(r)
+
+  assert.equal(w.length, 1)
+  assert.equal(w[0].params.type, 'ghost-station')
+})
+
+test('선언을 못 읽으면 카탈로그로 떨어진다 — 빈 목록으로 읽지 않는다', () => {
+  /*
+   * 「없는 것」과 「못 읽은 것」은 다르다. 못 읽은 것을 빈 목록으로 읽으면 **모든 자리가 경고**를 받고,
+   * 그것이 바로 이 시험이 막으려는 소음이다.
+   */
+  for (const broken of [{}, { definition: {} }, { definition: { locationTypes: [] } }, { definition: { locationTypes: 'nope' } }]) {
+    assert.equal(declaredLocationTypes(broken), undefined, `못 읽은 모양: ${JSON.stringify(broken)}`)
+  }
+
+  const r = masterToTwin(master(['raw-store', 'mixing'], { definition: { locationTypes: [] } }), CATALOG)
+  assert.equal(unknownWarnings(r).length, 1, '카탈로그 기준으로 하나만 경고한다')
+})
+
+test('선언 목록의 모양을 너그럽게 읽는다 — 문자열 목록도 받는다', () => {
+  assert.deepEqual(declaredLocationTypes({ definition: { locationTypes: ['mixing', 'packing'] } }), ['mixing', 'packing'])
+  assert.deepEqual(declaredLocationTypes({ definition: { locationTypes: [{ key: 'mixing' }, { nope: 1 }] } }), ['mixing'])
+})
+
+test('카탈로그도 선언도 없으면 아무 경고도 하지 않는다 — 모르는 것을 문제로 만들지 않는다', () => {
+  const r = masterToTwin(master(FNB), undefined)
+
+  assert.deepEqual(unknownWarnings(r), [], '견줄 상대가 없으면 판단하지 않는다')
+})

package/test/discovery-result.test.ts

@@ -65,7 +65,7 @@ test('타임아웃은 초 단위로 알린다 — 얼마를 기다렸는지 알
   assert.match(e.message, /15s/)
 })
 
-test('어댑터가 던진 것에서 사유를 뽑는다 — 형태를 가정하지 않는다', () => {
+test('어댑터가 낸 오류에서 사유를 뽑는다 — 형태를 가정하지 않는다', () => {
   assert.equal(detailOf(new Error('ECONNREFUSED')), 'ECONNREFUSED')
   assert.equal(detailOf('404 Not Found'), '404 Not Found')
   /* 무엇이 왔는지 모르면 그렇게 말한다 — 빈 문장으로 "이유 없음" 처럼 보이게 하지 않는다. */

package/test/duration-estimators.test.ts

@@ -123,7 +123,7 @@ test('p50 이 0 이면 쓰지 않는다 — 0 초 작업은 측정 실패다', (
   assert.deepEqual(r.learned, {})
 })
 
-test('그룹이 없으면 빈 결과 — 던지지 않는다', () => {
+test('그룹이 없으면 빈 결과 — 오류를 내지 않는다', () => {
   assert.equal(buildMeasuredEstimator(undefined).estimator, undefined)
   assert.equal(buildMeasuredEstimator([]).estimator, undefined)
 })

package/test/entity-delta.test.ts

@@ -118,7 +118,7 @@ test('물품 집약: 상한을 넘으면 잘린 사실을 밝힌다 — 조용
   assert.equal(agg.items.length, ITEMS_AGGREGATE_LIMIT)
   assert.equal(agg.total, ITEMS_AGGREGATE_LIMIT + 7)
   assert.equal(agg.truncated, 7)
-  /* 개별 물품은 상한과 무관하게 전부 태그별로 나간다(시그니처 dedup 이 변한 것만 재방송한다). */
+  /* 개별 물품은 상한과 무관하게 전부 태그별로 나간다(시그니처 dedup 이 변한 것만 재브로드캐스팅한다). */
   assert.equal(d.filter(x => x.data?.entity === 'item').length, ITEMS_AGGREGATE_LIMIT + 7)
 })
 
@@ -234,7 +234,7 @@ test('수요 구간·피크·계약은 집약 태그로 나간다 — 개체의
   assert.ok(agg, '집약 태그가 있어야 한다')
   assert.equal(agg.data.contractKW, 4000)
   assert.equal(agg.data.peakSince.kW, 4200)
-  /* 하루치를 매 방송에 실으면 채널이 그것으로 찬다 — 최근 것만 내고 전체 수를 함께 낸다. */
+  /* 하루치를 매 브로드캐스팅에 실으면 채널이 그것으로 찬다 — 최근 것만 내고 전체 수를 함께 낸다. */
   assert.equal(agg.data.recent.length, 8)
   assert.equal(agg.data.closedTotal, 137, '자른 사실을 조용히 두지 않는다')
 })

package/test/ingest-bench.test.ts

@@ -1,6 +1,6 @@
 /*
  * 커널 인제스트 인터페이스 부하 실측(가정 아닌 측정) — Face1/커널 동기 인터페이스의 처리량 특성.
- * apply(이벤트 흡수) · snapshot(전체 투영) · buildEntityDeltas(방송 payload, 't1') 의 비용을 규모별로 잰다.
+ * apply(이벤트 흡수) · snapshot(전체 투영) · buildEntityDeltas(브로드캐스팅 payload, 't1') 의 비용을 규모별로 잰다.
  * 결론은 design/integration/ingest-scale.md §커널 인터페이스에 스펙으로 반영.
  * (순수 커널+호스트 매핑, shell 무관 → node:test.)
  */
@@ -56,7 +56,7 @@ test('bench: buildEntityDeltas 비용 vs 엔티티 수 (전 엔티티 매번 방
   }
 })
 
-test('bench: 방송 1회 총비용(snapshot + buildEntityDeltas) vs 상태 규모', () => {
+test('bench: 브로드캐스팅 1회 총비용(snapshot + buildEntityDeltas) vs 상태 규모', () => {
   for (const [locations, items] of [[200, 5000], [1000, 50000], [2000, 100000]]) {
     const proj = new StateProjector(model(locations))
     for (let i = 0; i < items; i++) proj.apply(envelope(`urn:epc:id:sscc:0614141.${i}`, `bin-${i % locations}`))
@@ -64,6 +64,6 @@ test('bench: 방송 1회 총비용(snapshot + buildEntityDeltas) vs 상태 규
     const t0 = performance.now()
     for (let k = 0; k < iters; k++) buildEntityDeltas(proj.snapshot(), 't1')
     const per = (performance.now() - t0) / iters
-    console.log(`  [방송1회] ${locations.toLocaleString()} locations / ${items.toLocaleString()} items: ${per.toFixed(3)}ms → 최대 ${Math.round(1000 / per).toLocaleString()} 방송/s`)
+    console.log(`  [브로드캐스팅1회] ${locations.toLocaleString()} locations / ${items.toLocaleString()} items: ${per.toFixed(3)}ms → 최대 ${Math.round(1000 / per).toLocaleString()} 브로드캐스팅/s`)
   }
 })

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

@@ -0,0 +1,248 @@
+/*
+ * ★ 동기화 판정이 **실제 트윈 위에서** 옳게 나온다 — 엔진 이음새.
+ *
+ * 순수 모듈 시험(`ingest-health.test.ts`)은 「이런 장부가 주어지면 이런 판정」을 지킨다. 그런데 화면이
+ * 실제로 받는 판정은 그 앞에 한 층이 더 있다: **피드 사실을 어디서 얻는가**(`liveFeedStateOf` — 이 트윈이
+ * 미러인가 시뮬인가, 지금 도는가) 그리고 **장부를 어느 트윈의 것으로 찾는가**(도메인+인스턴스 키).
+ *
+ * 그 층이 틀리면 순수 시험은 전부 초록인 채로 화면만 거짓말한다. 실제로 두 가지가 조용히 틀릴 수 있다:
+ *  ① 시뮬 트윈이 「연결 안 됨」으로 보인다 — 거짓 경보이고, 거짓 경보는 참 경보를 죽인다
+ *  ② 남의 도메인 장부를 집는다 — 키를 도메인 없이 만들면 그렇게 된다
+ *
+ * 그래서 실 DataSource 로 트윈을 세우고, 미러 하나·시뮬 하나로 판정 여섯을 이 자리에서 확인한다.
+ * 목 HTTP 게이트웨이는 쓰지 않는다(그것은 데모 환경변수에 딸린 것이고, 여기서 볼 것은 장부와 판정이다).
+ */
+import { test, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+import type { DataSource } from 'typeorm'
+
+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')
+const { TwinEngine } = req('../dist-server/engine/index.js')
+const { INGEST_WINDOW_MS, STALE_AFTER_MS } = req('../dist-server/engine/ingest-health.js')
+const { registerLiveFeedProbe } = req('../dist-server/engine/live-feed-registry.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+/*
+ * 피드 사실을 이 시험이 쥔다.
+ *
+ * 실제 커넥터 피드는 원천에 붙어야 서고, 붙지 못하면 비동기로 떨어진다 — 그 타이밍에 판정이 흔들리면
+ * 이 시험은 **판정을 재는 게 아니라 커넥터를 재는 것**이 된다(실제로 그렇게 깨졌다: 세 번째 검사까지는
+ * 붙어 있다가 네 번째에서 떨어져 「연결 안 됨」이 나왔다). 그래서 `registerLiveFeedProbe` — 계층이 자기
+ * 장부를 등록하도록 만들어 둔 그 확장점 — 으로 시험의 장부를 하나 더 얹는다. 커넥터 거동은 커넥터
+ * 시험이 지킨다.
+ */
+let feedUp = new Set<string>()
+
+let ds: DataSource
+let domainId: string
+let otherDomainId: string
+
+/*
+ * 시나리오마다 트윈을 따로 둔다.
+ *
+ * 장부는 트윈마다 하나이고 **창은 이어진다.** 트윈 하나로 여러 시나리오를 돌리면 앞 검사가 남긴 창에
+ * 뒤 검사의 건수가 섞여 「최근 창」이 엉뚱한 것을 가리킨다(실제로 그렇게 깨졌다: 200건을 기대한 자리에
+ * 50건이 나왔다). 트윈을 나누면 각 검사가 자기 창만 본다.
+ */
+const MIRROR = 'sync-mirror' /* 붙었는데 아직 안 받음 → 창이 닫히면 동기화 중 */
+const BLOCKED = 'sync-blocked' /* 거부가 문턱을 넘음 */
+const STALE = 'sync-stale' /* 오래 끊김 */
+const SIM = 'sync-sim'
+const MIRRORS = [MIRROR, BLOCKED, STALE]
+
+/**
+ * 이 검사가 쓰는 창의 시작점.
+ *
+ * 창 하나를 닫고도 **읽는 시점이 다음 창 안에** 있어야 한다. `1.4창` 전에서 시작해 `창+1` 에서 닫으면
+ * 읽을 때까지 `0.4창`밖에 지나지 않아 두 번째 창이 닫히지 않는다 — 정확히 `2창` 전으로 잡았을 때
+ * 밀리초 몇 개 때문에 한 창이 더 닫혀 깨졌다.
+ */
+const windowStart = () => Date.now() - Math.floor(INGEST_WINDOW_MS * 1.4)
+
+const master = (source: string): any => ({
+  source,
+  system: 'wms',
+  siteName: '동기화 검사 창고',
+  space: { width: 40, depth: 20, unit: 'm' },
+  locations: [
+    { id: 'dock-recv', type: 'dock', role: 'location', name: '입고 도크', capacity: 100 },
+    { id: 'bin-1', type: 'storage', role: 'location', name: '빈1', capacity: 20 }
+  ],
+  equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'dock-recv' }]
+})
+
+/** 거부 하나 — 사유는 커널이 주는 모양을 그대로 흉내낸다(레코드 원문 포함). */
+const reject = (why: string) => ({ errors: [why], record: { epc: 'urn:epc:id:sgtin:0614141.107346.2018', bizStep: '?' } })
+
+before(async () => {
+  ds = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new NamingStrategy(),
+    entities: [...shellEntities, ...authEntities, ...twinEntities],
+    logging: false
+  })
+  await ds.initialize()
+  addDataSource('default', ds)
+  registerLiveFeedProbe(() => [...feedUp])
+
+  const d = await ds.getRepository(Domain).save({ name: 'sync-test', subdomain: 'sync-test' } as any)
+  domainId = d.id
+  const o = await ds.getRepository(Domain).save({ name: 'sync-other', subdomain: 'sync-other' } as any)
+  otherDomainId = o.id
+
+  for (const id of [...MIRRORS, SIM]) await TwinEngine.ingestMaster(domainId, master(id), 'reset')
+})
+
+after(async () => {
+  for (const id of [...MIRRORS, SIM]) await TwinEngine.stop(domainId, id).catch(() => {})
+  await ds?.destroy()
+})
+
+/** 미러로 세우고 피드를 붙인 상태로 만든다 — 각 검사가 자기 트윈을 자기 손으로 세운다. */
+async function bootMirror(instanceId: string): Promise<void> {
+  const rt = await TwinEngine.bootDeclared(domainId, instanceId, 'resync')
+  assert.equal(rt.mode, 'live', `${instanceId} 는 미러로 떠야 이 검사가 뜻이 있다`)
+  feedUp.add(instanceId)
+}
+
+test('시뮬 트윈은 「해당 없음」이다 — 물을 대상이 아닌 것에 경고색을 주지 않는다', async () => {
+  const rt = await TwinEngine.bootDeclared(domainId, SIM, 'reset')
+  assert.equal(rt.mode, 'sim', '시뮬로 떠야 이 검사가 뜻이 있다')
+
+  assert.equal(TwinEngine.ingestHealthOf(domainId, SIM).verdict, 'not-applicable')
+})
+
+test('미러가 붙었지만 아직 아무것도 안 받았으면 「모름」이다 — 정상도 비정상도 아니다', async () => {
+  await bootMirror(MIRROR)
+
+  const v = TwinEngine.ingestHealthOf(domainId, MIRROR)
+  assert.equal(v.verdict, 'unknown')
+  assert.equal(v.lastAt, null, '받은 적이 없다 — 0 이 아니다')
+  assert.equal(v.total.acceptedRatio, null, '비율이 없다 — 1 이 아니다')
+})
+
+test('창이 닫히면 「동기화 중」이 되고, 통과와 거부를 함께 낸다', () => {
+  const t0 = windowStart()
+
+  TwinEngine.recordIngestResult(domainId, MIRROR, 200, [reject('unknown bizStep "?"')], t0)
+  /* 창을 닫는다 — 창은 **다음 유입이 있을 때** 닫힌다. */
+  TwinEngine.recordIngestResult(domainId, MIRROR, 50, [], t0 + INGEST_WINDOW_MS + 1)
+
+  const v = TwinEngine.ingestHealthOf(domainId, MIRROR)
+  assert.equal(v.verdict, 'syncing')
+  assert.equal(v.recent.offered, 200)
+  assert.equal(v.recent.rejected, 1)
+  assert.equal(v.recent.accepted, 199)
+  assert.equal(v.recent.acceptedRatio, 0.995)
+  assert.equal(v.total.offered, 250, '누적은 두 창을 합한다')
+})
+
+test('거부가 문턱을 넘으면 「매핑이 막고 있음」이고, 사유와 레코드 원문이 함께 나온다', async () => {
+  await bootMirror(BLOCKED)
+  const t0 = windowStart()
+
+  TwinEngine.recordIngestResult(
+    domainId,
+    BLOCKED,
+    100,
+    Array.from({ length: 40 }, () => reject('unknown location "A-99"')),
+    t0
+  )
+  TwinEngine.recordIngestResult(domainId, BLOCKED, 1, [], t0 + INGEST_WINDOW_MS + 1)
+
+  const v = TwinEngine.ingestHealthOf(domainId, BLOCKED)
+  assert.equal(v.verdict, 'mapping-blocked')
+  assert.equal(v.recent.acceptedRatio, 0.6, '100건 중 40건이 거부됐다')
+
+  const reason = v.reasons.find((r: any) => r.reason === 'unknown location "A-99"')
+  assert.ok(reason, '사유를 묶어서 낸다')
+  assert.equal(reason.count, 40)
+
+  /* 표본은 커널이 낸 사유를 그대로 들고 있다(`errors`) — 우리가 다시 쓰지 않는다. */
+  const sample = v.samples.find((s: any) => s.errors.includes('unknown location "A-99"'))
+  assert.ok(sample, '사유만으로는 원천이 무엇을 보냈는지 알 수 없다 — 원문이 있어야 고친다')
+  assert.match(sample.record, /urn:epc:id:sgtin/, '레코드 원문이 그대로 들어 있다')
+})
+
+test('오래 끊긴 미러는 「유입 없음」이다 — 건강했던 옛 창으로 초록을 내지 않는다', async () => {
+  /*
+   * 이것이 이 기능이 있는 이유다. 창은 다음 유입이 있을 때 닫히므로, 유입이 멈추면 「최근 창」은 멈추기
+   * 직전의 건강했던 창으로 남는다. 그 창만 보면 어제 죽은 피드가 오늘도 「동기화 중」이다.
+   */
+  await bootMirror(STALE)
+  const long = Date.now() - STALE_AFTER_MS * 5
+
+  TwinEngine.recordIngestResult(domainId, STALE, 1000, [], long)
+  TwinEngine.recordIngestResult(domainId, STALE, 1000, [], long + INGEST_WINDOW_MS + 1) // 건강한 창을 닫는다
+
+  const v = TwinEngine.ingestHealthOf(domainId, STALE)
+  assert.equal(v.verdict, 'no-traffic', '마지막 유입이 한 창보다 오래 전이다')
+  assert.equal(v.recent.acceptedRatio, 1, '(옛 창 자체는 건강했다 — 그래서 창만 보면 속는다)')
+})
+
+test('피드가 떨어진 미러는 「연결 안 됨」이다 — 「유입 없음」과 처방이 다르다', () => {
+  /* 「유입 없음」은 원천·망을 보라는 말이고, 「연결 안 됨」은 결선하라는 말이다. 섞으면 엉뚱한 곳을 본다. */
+  feedUp.delete(MIRROR)
+
+  assert.equal(TwinEngine.ingestHealthOf(domainId, MIRROR).verdict, 'not-connected')
+
+  feedUp.add(MIRROR)
+})
+
+test('멈춘 미러는 「해당 없음」이다 — 고치려고 멈춰 둔 트윈에 「연결 안 됨」이라 하지 않는다', async () => {
+  await TwinEngine.stop(domainId, MIRROR)
+
+  const v = TwinEngine.ingestHealthOf(domainId, MIRROR)
+  assert.equal(v.verdict, 'not-applicable')
+  assert.ok(v.total.offered > 0, '멈춰도 장부는 남는다 — 마지막에 무엇이 거부됐는지 볼 수 있어야 한다')
+})
+
+test('멈춘 트윈에 계속 들어오면 「버려지는 중」이라 말한다 — 실제로 겪은 거짓 안심', async () => {
+  /*
+   * 겪은 모습: 트윈이 멈췄는데 피드는 살아 레코드를 나르고, 커널은 조용히 버렸다. 화면은 「해당 없음 ·
+   * 150 통과 · 100%」였다. 여기서는 그 상황을 그대로 만들어 판정과 수치를 확인한다.
+   */
+  /* 사람이 트윈을 멈춘다 — 그런데 피드는 남는다. 그 조합이 사실을 잃게 만든다. */
+  await TwinEngine.stop(domainId, STALE)
+  assert.equal(TwinEngine.instances[`${domainId}:${STALE}`], undefined, '멈췄다')
+
+  /* 커널이 받지 않는다 — `ingestLive` 가 0 을 돌려준다. */
+  const applied = TwinEngine.ingestLive(domainId, STALE, [{ any: 'envelope' } as any])
+  assert.equal(applied, 0, '멈춘 트윈은 봉투를 받지 않는다')
+
+  TwinEngine.recordIngestResult(domainId, STALE, 10, [], Date.now(), 10)
+
+  const v = TwinEngine.ingestHealthOf(domainId, STALE)
+  assert.equal(v.verdict, 'twin-not-running', '「해당 없음」으로 덮지 않는다')
+  assert.equal(v.total.undelivered >= 10, true, '버려진 수를 센다')
+})
+
+test('장부는 도메인으로 갈린다 — 같은 instanceId 라도 남의 것을 집지 않는다', () => {
+  const v = TwinEngine.ingestHealthOf(otherDomainId, MIRROR)
+
+  assert.equal(v.total.offered, 0, '다른 도메인에는 이 트윈의 장부가 없다')
+  assert.equal(v.total.acceptedRatio, null)
+  assert.equal(v.samples.length, 0, '남의 레코드 원문이 새지 않는다')
+})
+
+test('목록 요약은 숫자만 낸다 — 원문을 스무 벌 실어 조회를 무겁게 하지 않는다', () => {
+  const brief = TwinEngine.ingestHealthBrief(domainId, [MIRROR, SIM])
+
+  assert.equal(brief.length, 2)
+  const m = brief.find((b: any) => b.instanceId === MIRROR)
+  assert.ok(m, '멈춘 트윈도 목록에 남는다')
+  assert.equal((m as any).samples, undefined, '표본은 목록에 없다')
+  assert.equal((m as any).reasons, undefined, '사유도 목록에 없다')
+  assert.ok(Array.isArray((m as any).trend), '스파크라인용 추이는 있다')
+
+  const s = brief.find((b: any) => b.instanceId === SIM)
+  assert.equal((s as any).verdict, 'not-applicable')
+  assert.equal((s as any).acceptedRatio, null, '시뮬은 비율이 없다 — 0 이 아니다')
+})

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

@@ -0,0 +1,119 @@
+/*
+ * 유입 경로가 **모두 같은 장부**에 적는다 — 소스 규율 검사.
+ *
+ * ── 왜 기계가 지켜야 하나 ───────────────────────────────────────────────────
+ * 피드를 여는 경로가 둘이다(커넥터 `openLiveFeed` · 시나리오 `twin-ingest` 태스크). 한쪽만 장부에
+ * 적으면 그 경로로 먹이는 트윈이 **「한 번도 받지 않은 것」**으로 보인다. 그 판정은 `unknown` 이고,
+ * `unknown` 은 화면에서 「정상」과 구별되지 않는다 — 즉 **조용히 틀린 답**이 된다.
+ *
+ * 세 번째 경로가 생길 때 사람이 이 사실을 기억할 것이라고 믿지 않는다. 인제스트를 부르는 자리를
+ * 소스에서 찾아 장부 기록이 함께 있는지 본다.
+ */
+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 INGEST_CALL = 'ingestCanonicalRecords('
+
+/** 장부에 적는 창구. */
+const LEDGER_CALL = 'recordIngestResult('
+
+/**
+ * 예외 — 인제스트를 **부르지 않고 다시 내보내기만** 하는 자리.
+ *
+ * 늘리려면 이유를 함께 적는다. 「부르는데 안 적는다」는 예외가 될 수 없다 — 그게 이 검사가 막는 것이다.
+ */
+const REEXPORT_ONLY = ['board/tasks/twin-ingest-core.ts', 'engine/index.ts', 'engine/canonical-ingest.ts']
+
+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] : []
+  })
+}
+
+function ingestCallSites(): { file: string; src: string }[] {
+  const out: { file: string; src: string }[] = []
+  for (const root of ROOTS) {
+    for (const f of sources(root)) {
+      const src = readFileSync(f, 'utf-8')
+      if (!src.includes(INGEST_CALL)) continue
+      const rel = f.slice(root.length + 1)
+      if (REEXPORT_ONLY.some(x => rel.endsWith(x))) continue
+      out.push({ file: rel, src })
+    }
+  }
+  return out
+}
+
+test('인제스트를 부르는 곳은 모두 장부에 적는다 — 한 경로만 빠지면 그 트윈은 「모름」으로 보인다', () => {
+  const missing = ingestCallSites()
+    .filter(s => !s.src.includes(LEDGER_CALL))
+    .map(s => s.file)
+
+  assert.deepEqual(
+    missing,
+    [],
+    `장부에 적지 않는 유입 경로 ${missing.length}곳:\n  ${missing.join('\n  ')}\n\n` +
+      `그 경로로 먹이는 트윈은 twinIngestHealth 에서 「한 번도 받지 않음」(unknown)으로 보이고, ` +
+      `화면에서 정상과 구별되지 않는다. TwinEngine.recordIngestResult(도메인, 인스턴스, 제시수, 거부) 를 부른다.`
+  )
+})
+
+test('검사가 실제로 경로를 보고 있다 — 대상이 사라지면 초록이 거짓이 된다', () => {
+  const sites = ingestCallSites().map(s => s.file)
+
+  assert.ok(
+    sites.length >= 2,
+    `유입 경로를 ${sites.length}곳 찾았다 — 둘(커넥터·시나리오)보다 적으면 호출 형태가 바뀐 것이다. ` +
+      `이 검사의 패턴을 함께 옮긴다. 찾은 것: ${sites.join(', ') || '없음'}`
+  )
+})
+
+test('유입 경로는 커널이 실제로 받은 수를 견준다 — 버려진 것을 통과로 세지 않게', () => {
+  /*
+   * 겪은 일: 트윈이 멈춘 뒤에도 피드는 레코드를 나르고 커널은 조용히 버렸는데, 장부는 그것을 「통과」로
+   * 셌다. 화면은 멈춘 트윈 옆에 「150 통과 · 100%」라고 적었다 — 사실이 사라지는 동안 안심시킨 것이다.
+   *
+   * 고친 방법은 `ingestLive` 가 **넣은 수를 돌려주는** 것이다. 새 경로가 그 반환을 안 쓰고 0 을 넘기면
+   * 같은 침묵이 돌아온다. 그래서 경로마다 미전달을 세는지 소스에서 본다.
+   */
+  const missing = ingestCallSites()
+    .filter(s => !s.src.includes('undelivered'))
+    .map(s => s.file)
+
+  assert.deepEqual(
+    missing,
+    [],
+    `커널이 받은 수를 견주지 않는 유입 경로 ${missing.length}곳:\n  ${missing.join('\n  ')}\n\n` +
+      `TwinEngine.ingestLive(...) 의 반환(넣은 수)을 받아 accepted.length 와의 차이를 ` +
+      `recordIngestResult(..., nowMs, undelivered) 로 넘긴다. 그러지 않으면 트윈이 멈춘 사이 ` +
+      `버려진 레코드가 「통과」로 집계되어 화면이 100% 라고 말한다.`
+  )
+})
+
+test('제시 수를 거부 수로 대신하지 않는다 — 통과율의 분모가 뒤바뀌지 않게', () => {
+  /*
+   * 실수하기 쉬운 자리다: `recordIngestResult(..., rejected.length, rejected)` 처럼 적으면 분모가
+   * 거부 수가 되어 **통과율이 언제나 0** 이 된다. 오류 없이 「전부 거부」로 읽힌다.
+   */
+  const bad = ingestCallSites()
+    .filter(s => /recordIngestResult\([^)]*rejected\.length\s*,/.test(s.src))
+    .map(s => s.file)
+
+  assert.deepEqual(bad, [], `제시 수 자리에 거부 수를 넘긴 곳:\n  ${bad.join('\n  ')}`)
+})