@things-factory/headless-twin 10.0.11 → 10.0.13

package/test/control-capability.test.ts

@@ -0,0 +1,103 @@
+/*
+ * **구동은 선언된 능력이다** — 그리고 원본을 지난다 (ADR-0029 §8, 2026-08-19).
+ *
+ * ── 무엇이 뚫려 있었나 ──────────────────────────────────────────────────────
+ * `controlTwinScenario` 가 트윈의 커널 런타임(`runtime.scenario`)을 **직접** 잡았다. 시뮬만 할 수 있는 일
+ * (자극·배속·정지)이 계약 밖의 지름길로 들어온 셈이고, 실 시스템에는 그 자리가 아예 없었다. ADR-0029 의
+ * 판정 문장(*"실물이 같은 계약으로 할 수 있는가"*)을 그대로 대면 그 통제면은 영원히 「규약의 결손」이 된다.
+ *
+ * 뒤집는다: 통제는 **선언된 어댑터 능력**이다. 선언하지 않은 원본에는 문이 열리지 않고, 그 사실이 결손이
+ * 아니라 사실이다(실 WMS 는 정지되지 않는다).
+ *
+ * 이 시험이 지키는 것:
+ *  ① 선언과 구현이 **함께** 있어야 능력이다 — 선언만 있으면 화면이 거짓말을 하고, 구현만 있으면 닫아 둔
+ *    문을 여는 것이다(선언이 권위다).
+ *  ② 능력 없는 원본은 **사유 코드로** 거절한다(조용한 실패 금지).
+ *  ③ 없는 기능을 있는 것처럼 답하지 않는다(내장 시뮬은 아직 재씨앗을 못 한다).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { capabilitiesOf, type ReferenceAdapter } from '../server/service/reference/reference-adapter.ts'
+
+const base: ReferenceAdapter = {
+  type: 'probe',
+  async testConnection() {
+    return { ok: true }
+  },
+  async discoverSites() {
+    return []
+  },
+  async fetchMaster() {
+    return { source: 'p', system: 'wms', space: { spaceId: 'p-site' }, locations: [] } as any
+  }
+}
+
+test('선언도 구현도 없으면 아무 능력이 없다 — 구조만 주는 원본이 정상이다', () => {
+  assert.deepEqual(capabilitiesOf(base), [])
+})
+
+test('선언만 있으면 능력이 아니다 — 화면이 「할 수 있다」고 말한 뒤 아무 일도 없게 두지 않는다', () => {
+  assert.deepEqual(capabilitiesOf({ ...base, capabilities: ['control'] }), [])
+  assert.deepEqual(capabilitiesOf({ ...base, capabilities: ['live'] }), [])
+})
+
+test('구현만 있으면 능력이 아니다 — 선언이 권위다(닫아 둔 문을 열지 않는다)', () => {
+  assert.deepEqual(capabilitiesOf({ ...base, control: async () => ({ ok: true }) }), [])
+  assert.deepEqual(capabilitiesOf({ ...base, openLiveFeed: () => () => {} }), [])
+})
+
+test('선언과 구현이 함께 있으면 그 능력이다', () => {
+  assert.deepEqual(capabilitiesOf({ ...base, capabilities: ['control'], control: async () => ({ ok: true }) }), ['control'])
+  assert.deepEqual(
+    capabilitiesOf({
+      ...base,
+      capabilities: ['live', 'control'],
+      openLiveFeed: () => () => {},
+      control: async () => ({ ok: true })
+    }),
+    ['live', 'control']
+  )
+})
+
+test('어댑터가 없으면 빈손이다 — 지어내지 않는다', () => {
+  assert.deepEqual(capabilitiesOf(undefined), [])
+})
+
+/*
+ * ── 길이 하나뿐인지 (소스로 지킨다) ────────────────────────────────────────
+ * 지름길이 남아 있으면 이 결정은 문서상의 것이 된다. 그래서 ① 구동 문이 라우터를 지나고 ② 라우터가 능력을
+ * 보고 ③ 트윈 런타임을 직접 잡는 옛 경로가 사라졌는지 본다.
+ */
+test('구동 문이 원본을 지난다 — 트윈 런타임을 직접 잡지 않는다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/service/twin-control/twin-control-mutation.ts', import.meta.url)), 'utf-8')
+  const code = src
+    .split('\n')
+    .filter(line => !/^\s*(\*|\/\/|\/\*)/.test(line))
+    .join('\n')
+  assert.match(code, /routeControl\(domainId, instanceId/, '구동은 라우터를 지난다')
+  assert.equal(/runtime\.scenario\./.test(code), false, '트윈의 시나리오 엔진을 직접 잡는 지름길이 없다')
+  assert.equal(/controlTwinScenario/.test(code), false, '옛 문이 남아 있지 않다')
+  assert.match(code, /twinSourceCapability/, '화면이 먼저 물을 자리가 있다')
+})
+
+test('라우터가 선언을 본다 — 없으면 사유 코드로 거절한다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/service/reference/control-routing.ts', import.meta.url)), 'utf-8')
+  assert.match(src, /capabilitiesOf\(adapter\)\.includes\('control'\)/)
+  assert.match(src, /'not-declared'/)
+  assert.match(src, /'no-source'/, '원본을 모르는 트윈은 구동 대상이 아니다')
+})
+
+test('내장 시뮬은 자기가 못 하는 것을 못 한다고 말한다 — 재씨앗은 아직 없다', () => {
+  const src = readFileSync(
+    fileURLToPath(new URL('../../operato-twin/server/board/virtual-adapter.ts', import.meta.url)),
+    'utf-8'
+  )
+  /* §4 이후 이 원본은 둘을 선언한다(`live`·`control`) — 순서가 아니라 **있음**을 본다. */
+  assert.match(src, /capabilities: \[[^\]]*'control'[^\]]*\]/, '구동 능력을 선언한다')
+  assert.match(src, /capabilities: \[[^\]]*'live'[^\]]*\]/, '피드 능력도 선언한다(§4)')
+  assert.match(src, /cannot re-seed itself yet/, '없는 기능을 있는 것처럼 답하지 않는다')
+  assert.match(src, /not-running/, '아직 서지 않은 트윈에는 자극을 지어 싣지 않는다')
+})

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/declared-stimulus.test.ts

@@ -0,0 +1,88 @@
+/*
+ * 자극은 **원본이 선언한다** — 그리고 재기동에도 살아 있다.
+ *
+ * ── 무엇이 났나 (2026-08-19) ────────────────────────────────────────────────
+ * 데모의 시나리오는 시드 코드가 **메모리에만** 실었다(`runtime.scenario.load`). 그래서 트윈을 재기동하면
+ * 자극이 사라지고 구조만 서 있는 트윈이 남았다 — 작업 0·오더 0. 「살아 있는 데모」가 첫 재기동까지만
+ * 살았고, 오늘 서버를 여러 번 띄우는 동안 데모 트윈들이 실제로 그 상태였다.
+ *
+ * ── 집을 트윈이 아니라 원본으로 (ADR-0029 · plans/simulator-as-source.md §4) ─
+ * 무엇이 들어오고 무슨 주문이 나는지는 **시뮬레이터(원본)가 정하는 사실**이고 트윈은 반영한다. 트윈에
+ * 축을 만들면 ADR-0029 가 나중에 걷어내야 하고, 원본(`TwinReference.connectionConfig`)에 두면 그 계획의
+ * 첫 조각(`openLiveFeed`)이 같은 선언을 그대로 읽는다.
+ *
+ * 이 시험이 지키는 것:
+ *  ① 선언이 없으면 조용히 지난다(정적 구조만 반영하는 트윈이 정상이다).
+ *  ② **미러에는 싣지 않는다** — 외부 실물이 진실인 트윈에 도착을 지어 주면 그것은 현실이 아니다.
+ *  ③ 검사를 통과하지 못한 선언은 **태우지 않고** 이유를 남긴다(잘못된 선언 하나가 서버를 내린 이력이 있다).
+ *  ④ 검사기가 없으면 싣지 않는다 — 검사할 수 없는 선언을 태우는 것이 가장 비싼 선택이다.
+ *  ⑤ 선언을 얹을 때 **옆 설정을 지우지 않는다**(접속 정보가 같은 자리에 산다).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { planStimulus, withStimulus } from '../server/engine/declared-stimulus.ts'
+
+const scenario = { seed: 1, generators: [{ kind: 'inbound-arrival', rate: { distribution: 'constant', meanPerHour: 60 }, content: {} }] }
+const ok = () => ({ ok: true as const })
+const bad = () => ({ ok: false as const, errorCode: 'scenario-sku-mix-required' })
+const sim = { hasScenarioEngine: true, mode: 'sim' as const }
+
+test('선언이 없으면 조용히 지난다 — 구조만 반영하는 트윈이 정상이다', () => {
+  assert.deepEqual(planStimulus(undefined, sim, ok), { action: 'skip', reason: 'none' })
+  assert.deepEqual(planStimulus({ endpoint: 'x' }, sim, ok), { action: 'skip', reason: 'none' })
+  /* 시나리오 자리에 객체가 아닌 것이 오면 선언이 아니다(문자열을 시나리오로 읽지 않는다). */
+  assert.deepEqual(planStimulus({ scenario: 'daily' }, sim, ok), { action: 'skip', reason: 'none' })
+})
+
+test('관측으로 도는 트윈에는 싣지 않는다 — 현실을 지어내지 않는다', () => {
+  const plan = planStimulus({ scenario }, { hasScenarioEngine: true, mode: 'live' }, ok)
+  assert.deepEqual(plan, { action: 'skip', reason: 'observed' })
+})
+
+test('시나리오 엔진이 없으면 싣지 않는다 — 조용히 아무 일도 없게 두지 않는다', () => {
+  const plan = planStimulus({ scenario }, { hasScenarioEngine: false, mode: 'sim' }, ok)
+  assert.deepEqual(plan, { action: 'skip', reason: 'no-engine' })
+})
+
+test('검사를 통과하지 못한 선언은 태우지 않는다 — 사유를 든다', () => {
+  const plan = planStimulus({ scenario }, sim, bad)
+  assert.deepEqual(plan, { action: 'skip', reason: 'invalid', detail: 'scenario-sku-mix-required' })
+})
+
+test('검사기가 없으면 싣지 않는다 — 검사할 수 없는 선언이 가장 위험하다', () => {
+  const plan = planStimulus({ scenario }, sim, undefined)
+  assert.equal(plan.action, 'skip')
+  assert.equal((plan as any).reason, 'invalid')
+})
+
+test('통과한 선언은 그대로 싣는다 — 값을 손대지 않는다', () => {
+  const plan = planStimulus({ scenario }, sim, ok)
+  assert.deepEqual(plan, { action: 'load', scenario })
+})
+
+test('선언을 얹으면서 접속 정보를 지우지 않는다', () => {
+  const merged = withStimulus({ endpoint: 'https://sim', token: 't' }, scenario)
+  assert.deepEqual(merged, { endpoint: 'https://sim', token: 't', scenario })
+  /* 설정이 없던 원본에도 얹힌다(빈 객체에서 시작). */
+  assert.deepEqual(withStimulus(undefined, scenario), { scenario })
+})
+
+/*
+ * ── 배선 (소스로 지킨다) ────────────────────────────────────────────────────
+ * 판정은 순수 함수가 하지만, 그것을 **기동 때 부르지 않으면** 아무 일도 일어나지 않는다. 그리고 못 실은
+ * 이유는 말해야 한다 — 「선언했는데 안 실렸다」가 조용하면 사용자는 트윈이 고장 난 줄로 읽는다.
+ */
+test('두 기동 경로에서 부른다 — 시뮬은 싣고, 미러는 그 사실을 말한다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/engine/twin-engine.ts', import.meta.url)), 'utf-8')
+  const calls = src.match(/this\.installStimulus\(domainId, id, inst\)/g) ?? []
+  assert.equal(calls.length, 2, `기동 경로 둘에서 불러야 한다(발견 ${calls.length})`)
+  assert.match(src, /planStimulus\(config, \{ hasScenarioEngine/, '판정은 순수 함수에 맡긴다')
+  assert.match(src, /validateScenario/, '커널 검사기를 그대로 쓴다(규칙을 두 벌로 만들지 않는다)')
+  assert.match(src, /a stimulus is declared on its source but was not loaded/, '못 실은 이유를 말한다')
+  /* 선언을 적는 문도 있어야 한다 — 읽기만 있으면 아무도 선언할 수 없다. */
+  assert.match(src, /static async declareStimulus/)
+  assert.match(src, /no source reference — a stimulus has nowhere to be declared/, '원본이 없으면 지어 만들지 않는다')
+})

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 이 아니다')
+})