@things-factory/headless-twin 10.0.12 → 10.0.14

package/test/broadcast-period.test.ts

@@ -0,0 +1,58 @@
+/*
+ * 브로드캐스팅 주기는 **재 본 비용에 맞춘다** (2026-08-21).
+ *
+ * 한 번의 브로드캐스팅은 상태 크기에 비례한다(실측: 물품 2,400 개 트윈 하나가 4.5ms). 트윈이 스무 개면
+ * 200ms 주기에서 90ms 가 브로드캐스팅이고, 그 시간에는 HTTP 도 구독도 서지 못한다. 그래서 브로드캐스팅이 주기의
+ * 일정 몫을 넘게 쓰면 주기를 늘리고, 여유가 생기면 되돌린다.
+ *
+ * 지키는 것:
+ *  ① 무거우면 늘린다 — 상한까지만.
+ *  ② 가벼워지면 되돌린다 — 원래 주기 아래로는 내려가지 않는다.
+ *  ③ 경계에서 늘리고 줄이기를 반복하지 않는다(문턱이 둘이다).
+ *  ④ **늘렸다는 사실을 센다** — 조용히 늦추면 사람은 화면이 낡은 이유를 알 수 없다.
+ */
+import { test, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+
+const req = createRequire(import.meta.url)
+const { TwinEngine } = req('../dist-server/engine/twin-engine.js')
+
+/** 주기 조정만 부른다 — 실제 브로드캐스팅(pubsub·DB)은 이 판정과 무관하다. */
+const adjust = (flushMs: number) => (TwinEngine as any).adjustBroadcastPeriod(flushMs)
+
+beforeEach(() => {
+  TwinEngine.broadcastPeriodMs = TwinEngine.BROADCAST_COALESCE_MS
+  TwinEngine.broadcastBackoffs = 0
+})
+
+test('브로드캐스팅이 주기의 몫을 넘게 쓰면 주기를 늘린다 — 상한까지만', () => {
+  const base = TwinEngine.BROADCAST_COALESCE_MS
+  adjust(base) // 주기를 통째로 쓴 셈
+  assert.equal(TwinEngine.broadcastPeriodMs, base * 2)
+
+  for (let i = 0; i < 10; i++) adjust(TwinEngine.broadcastPeriodMs)
+  assert.equal(TwinEngine.broadcastPeriodMs, TwinEngine.BROADCAST_MAX_COALESCE_MS, '상한 위로는 올라가지 않는다')
+})
+
+test('늘렸다는 사실을 센다 — 조용히 늦추지 않는다', () => {
+  adjust(TwinEngine.BROADCAST_COALESCE_MS)
+  assert.equal(TwinEngine.broadcastBackoffs, 1)
+})
+
+test('가벼워지면 되돌린다 — 원래 주기 아래로는 내려가지 않는다', () => {
+  adjust(TwinEngine.BROADCAST_COALESCE_MS) // 200 → 400
+  assert.ok(TwinEngine.broadcastPeriodMs > TwinEngine.BROADCAST_COALESCE_MS)
+
+  for (let i = 0; i < 10; i++) adjust(0.5)
+  assert.equal(TwinEngine.broadcastPeriodMs, TwinEngine.BROADCAST_COALESCE_MS)
+})
+
+test('경계에서 늘리고 줄이기를 반복하지 않는다 — 문턱이 둘이다', () => {
+  const base = TwinEngine.BROADCAST_COALESCE_MS
+  /* 늘리는 문턱(몫)과 되돌리는 문턱(몫의 절반) 사이의 값 — 어느 쪽도 아니어야 한다. */
+  const between = base * TwinEngine.BROADCAST_LOAD_RATIO * 0.75
+  for (let i = 0; i < 5; i++) adjust(between)
+  assert.equal(TwinEngine.broadcastPeriodMs, base, '문턱 사이의 값은 주기를 바꾸지 않는다')
+  assert.equal(TwinEngine.broadcastBackoffs, 0)
+})

package/test/canonical-ingest-vocabularies.test.ts

@@ -79,7 +79,7 @@ test('설비 에너지 상태는 EPCIS 도 계량도 아닌 자기 어휘로 들
     [
       { equipmentId: 'pv-1', at: '2026-08-15T09:00:00.000Z', generatedKW: 210 },
       { meterId: 'm-1', kW: 800, at: '2026-08-15T09:00:00.000Z' },
-      { epc: 'urn:epc:id:sgtin:1.2.3', action: 'OBSERVE', bizStep: 'urn:epcglobal:cbv:bizstep:storing' }
+      { epc: 'urn:epc:id:sgtin:9521321.012345.3', action: 'OBSERVE', bizStep: 'urn:epcglobal:cbv:bizstep:storing' }
     ] as any,
     'tenant-1',
     '2026-08-15T09:00:00.000Z'
@@ -116,3 +116,38 @@ test('개폐 위치는 표준의 네 값만 받는다 — 과도·불량을 열
   assert.equal(bad.rejected.length, 1)
   assert.match(bad.rejected[0].errors.join(' '), /position/)
 })
+
+/*
+ * ── 레코드가 말한 시각이 봉투의 시각이 된다 (2026-08-23) ────────────────────
+ *
+ * 이 경로는 `eventTimePath` 를 주지 않아 **언제나 폴링 시각**을 썼다. 그래서 커넥터가 이미 싣고 있던
+ * `eventTime` 이 조용히 무시됐다 — 어디에도 오류가 나지 않고, 커넥터를 붙인 쪽은 그것이 먹는다고
+ * 믿고 있었다.
+ *
+ * 무엇이 걸렸나: **계보의 시각**이다. 4월에 만든 로트가 8월에 만들어진 것으로 저널에 남았다. 그리고
+ * 실측 소요를 재는 폴드가 봉투 시각을 쓰므로(`kpi-fold`: `workMs = 완료 − 첫 착수`), 폴링 간격을
+ * 작업시간으로 배울 수 있었다 — 못 배우는 것보다 나쁘다.
+ */
+test('레코드가 시각을 말하면 그것이 봉투의 시각이다 — 폴링 시각으로 덮지 않는다', () => {
+  const POLLED = '2026-08-23T00:00:00.000Z'
+  const SAID = '2026-04-15T07:35:53.000Z'
+  const { accepted, rejected } = ingestCanonicalRecords(
+    [{ ...epcisRecord, eventTime: SAID }] as any,
+    't',
+    POLLED
+  )
+  assert.deepEqual(rejected, [])
+  assert.equal(accepted[0].eventTime, SAID, '원본이 말한 시각이어야 한다')
+  assert.notEqual(accepted[0].eventTime, POLLED, '폴링 시각이 아니어야 한다')
+})
+
+test('레코드가 시각을 말하지 않으면 폴링 시각으로 떨어진다 — 이 한 줄이 기존 경로를 막지 않는다', () => {
+  /*
+   * 커널의 경로 해석은 없는 값을 **오류로 만들지 않는다**(§`resolve`). 그래서 시각을 말하지 않는
+   * 레코드는 예전처럼 기본값을 쓴다. 이 단정이 없으면 위 한 줄이 조용히 대량 거부를 낼 수 있다.
+   */
+  const POLLED = '2026-08-23T00:00:00.000Z'
+  const { accepted, rejected } = ingestCanonicalRecords([epcisRecord] as any, 't', POLLED)
+  assert.deepEqual(rejected, [])
+  assert.equal(accepted[0].eventTime, POLLED)
+})

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/checkpoint-refuses-empty.test.ts

@@ -0,0 +1,103 @@
+/*
+ * ★ **아무것도 듣지 못한 것을 「비었다」로 적지 않는다** — 체크포인트가 좋은 스냅샷을 덮지 않게.
+ *
+ * ── 무엇이 손실을 영구화하고 있었나 (2026-08-24 실측) ────────────────────────
+ * 미러가 재기동하면 관측 축(재고·오더·작업)을 들고 오지 않는다(`startLive` 가 되찾은 상태를 버린다 —
+ * 「다음 계측이 정정한다」는 전제). 그런데 원본이 **커서 증분**으로 말하는 현장에서는 그 정정이 오지
+ * 않는다: 커서가 따라잡힌 뒤 원본이 변하지 않으면 미러는 영구히 빈 채다.
+ *
+ * 실측(포천, `operato-chef-v1-pocheon`):
+ *
+ *   저널을 접으면        items 741 · orders 2,856 · tasks 9,250 · nowTime 2026-04-15
+ *   라이브 미러          items   0 · orders     0 · tasks     0 · nowTime 2026-01-01
+ *   저장된 스냅샷        rev 221,884 · items 741 · orders 2,780 · tasks 6,353  (어제 것)
+ *   그런데 이 판이       같은 키에 **빈 상태**를 쓰고 있었다
+ *
+ * 그러면 되살릴 캐시가 사라진다. 재기동이 상태를 버리는 것은 저널에서 되살릴 수 있지만, **캐시를
+ * 지우는 것은 그 복구 수단을 함께 지운다.**
+ *
+ * ── 왜 리비전으로는 막을 수 없나 ────────────────────────────────────────────
+ * 저널 줄 번호는 **관측이 없어도 자란다**(다른 축·다른 트윈의 사건, 체크포인트 자체). 그래서
+ * 「리비전이 더 크면 진전」이라는 규칙은 빈 상태를 통과시킨다.
+ *
+ * 막는 기준은 **「들은 것이 있나」**다. 유입이 한 건도 없었다면 그 빈 상태는 원본이 「비었다」고
+ * 말한 것이 아니라 **우리가 아무것도 못 들은 것**이다 — 그 둘을 같은 값으로 적으면 「모름」이
+ * 「없음」이 된다. 이 저장소가 여러 번 거절한 모양이다.
+ *
+ * 원본이 실제로 「다 비었다」고 말한 경우는 막지 않는다 — 그때는 유입이 있었으므로 이 문을 지난다.
+ *
+ * ── 엔진 본체는 부를 수 없다 ────────────────────────────────────────────────
+ * DB 를 물고 있어 시험에서 부르지 못한다(§`snapshot-freshness` 와 같은 사정). 그래서 판정식만 떼어
+ * 시험하고, **그 식이 엔진에 실제로 있는지**를 소스로 함께 확인한다 — 식만 시험하면 엔진이 그것을
+ * 쓰지 않아도 초록이다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 엔진의 조건과 같은 식(`twin-engine.persistSnapshot`). */
+const observed = (s: any): number => (s?.items?.length ?? 0) + (s?.orders?.length ?? 0) + (s?.tasks?.length ?? 0)
+
+const refuses = (live: any, stored: any, ingestedTotal: number): boolean =>
+  !(ingestedTotal > 0) && observed(live) === 0 && observed(stored) > 0
+
+const RICH = { items: [{ epc: 'a' }], orders: [{ id: 'o' }], tasks: [{ id: 't' }] }
+const EMPTY = { items: [], orders: [], tasks: [] }
+
+test('못 들었고 라이브가 비었는데 저장된 것에 사실이 있으면 — **거절한다**', () => {
+  /* ★ 이 시험이 막는 것. 통과시키면 되살릴 유일한 사본이 사라진다. */
+  assert.equal(refuses(EMPTY, RICH, 0), true)
+})
+
+test('들은 것이 있으면 통과한다 — 원본이 「다 비었다」고 말한 것은 사실이다', () => {
+  /*
+   * 창고가 실제로 비는 것은 정상이다. 그때는 유입이 있었으므로 그 빈 상태가 **관측**이고,
+   * 여기서 막으면 스냅샷이 영구히 낡는다(고치려던 것의 반대 방향으로 틀린다).
+   */
+  assert.equal(refuses(EMPTY, RICH, 1), false)
+  assert.equal(refuses(EMPTY, RICH, 24839), false)
+})
+
+test('라이브에 사실이 있으면 통과한다 — 못 들었어도 심어진 상태는 지킬 값이다', () => {
+  assert.equal(refuses(RICH, RICH, 0), false)
+})
+
+test('저장된 것이 비어 있으면 막을 것이 없다 — 첫 체크포인트를 가로막지 않는다', () => {
+  /* 처음 뜬 트윈은 저장된 것이 없다. 여기서 막으면 그 트윈은 영원히 스냅샷을 갖지 못한다. */
+  assert.equal(refuses(EMPTY, EMPTY, 0), false)
+  assert.equal(refuses(EMPTY, null, 0), false)
+  assert.equal(refuses(EMPTY, undefined, 0), false)
+})
+
+test('축 하나만 남아도 사실이다 — 셋을 합쳐 센다', () => {
+  /*
+   * 오더만 남고 재고가 빈 상태는 흔하다(다 내보낸 창고). 축마다 따로 판정하면 그 상태가
+   * 「비었다」로 읽힌다.
+   */
+  assert.equal(refuses(EMPTY, { items: [], orders: [{ id: 'o' }], tasks: [] }, 0), true)
+  assert.equal(refuses(EMPTY, { items: [], orders: [], tasks: [{ id: 't' }] }, 0), true)
+})
+
+test('리비전은 판정에 쓰지 않는다 — 저널 번호는 관측이 없어도 자란다', () => {
+  /*
+   * ★ 이 단정이 **틀린 기준으로 돌아가는 것**을 막는다. 실측에서 저장된 스냅샷의 리비전은 221,884
+   * 였고 라이브는 그보다 큰 번호를 들고 있었다 — 리비전을 기준으로 삼으면 빈 상태가 통과한다.
+   */
+  const live = { ...EMPTY, revision: 999999 }
+  const stored = { ...RICH, revision: 1 }
+  assert.equal(refuses(live, stored, 0), true, '번호가 커도 사실이 없으면 덮지 않는다')
+})
+
+test('엔진이 실제로 이 판정을 한다 — 식만 시험하면 엔진이 안 써도 초록이다', () => {
+  const src = readFileSync(join(import.meta.dirname, '..', 'server', 'engine', 'twin-engine.ts'), 'utf8')
+  /* 주석을 걷어낸 코드만 — 「덮지 않는다」를 적어 둔 근거가 가드를 뒤집지 않게. */
+  const code = src.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/(^|[^:])\/\/.*$/gm, '$1')
+  const at = code.indexOf('persistSnapshot')
+  assert.ok(at > 0, 'persistSnapshot 이 있어야 한다')
+  const body = code.slice(at, at + 2000)
+  assert.match(body, /ingestedTotal/, '「들은 것이 있나」를 본다')
+  assert.match(body, /items\?\.length[\s\S]{0,80}orders\?\.length[\s\S]{0,80}tasks\?\.length/, '관측 축 셋을 합쳐 센다')
+  assert.match(body, /checkpoint refused/, '거절을 말한다 — 조용히 거절하지 않는다')
+  assert.doesNotMatch(body.slice(0, body.indexOf('checkpoint refused')), /revision >|revision </, '리비전 비교로 판정하지 않는다')
+})

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/cursor-stall-not-read-failure.test.ts

@@ -0,0 +1,126 @@
+/*
+ * ★ **조치가 반대인 두 사실을 한 이름으로 부르면 그 이름은 정보가 아니라 오해다.**
+ *
+ * ── 무엇이 반대 방향을 가리켰나 (2026-08-24) ────────────────────────────────
+ * 2026-08-23 에 「원본에 닿지 못한다」를 트윈이 말할 수 있게 `onReadFailure` 를 만들었다. 그런데 그 문으로
+ * **다른 사실**이 함께 나가고 있었다.
+ *
+ *   원본에 닿지 못했다        접속 실패·시간 초과 → **기다리면 풀린다**
+ *   읽었는데 커서가 못 넘어간다  한 시각에 한 페이지보다 많은 행 → **기다려도 안 풀린다**
+ *
+ * 둘째는 **읽기가 성공한 실패**다. 원본은 답했고 그 답의 모양이 커서를 이겼다. 그런데 화면이
+ * 「원본에 닿지 못한다」고 말하면 사람은 원본을 의심하고 기다린다 — 실제로 필요한 조치는 페이지를
+ * 키우거나 같은 시각 안에서 순서를 정하는 것이고, 기다림으로는 영원히 풀리지 않는다.
+ *
+ * 게다가 그 문구가 스트림 이름을 꺼내는 규칙에 맞지 않아 **어느 표가 막혔는지도 남지 않았다.**
+ *
+ * ── 이 시험이 지키는 것 ─────────────────────────────────────────────────────
+ * ① 두 축이 **서로를 지우지 않는다**  ② 두 축이 **각자 뷰로 나간다**(유입이 없는 갈래에서도)
+ * ③ 「몇 번·언제부터」를 정체 쪽도 든다  ④ 넘어가면 지운다
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  clearCursorStall,
+  clearReadFailure,
+  ingestHealth,
+  newIngestLedger,
+  recordCursorStall,
+  recordIngest,
+  recordReadFailure
+} from '../server/engine/ingest-health.ts'
+
+const T0 = Date.parse('2026-08-24T06:00:00.000Z')
+
+test('정체는 읽기 실패와 **다른 칸**이다 — 서로를 지우지 않는다', () => {
+  /*
+   * ★ 한 칸을 쓰면 나중에 온 것이 앞의 것을 덮는다. 그러면 「닿지 못한다」와 「못 넘어간다」 중
+   * 마지막 것만 남고, 화면은 조치를 반대로 안내할 수 있다.
+   */
+  const l = newIngestLedger()
+  recordReadFailure(l, 'connect ETIMEDOUT', T0, 'inventory')
+  recordCursorStall(l, 'one timestamp holds more rows than a page', T0 + 1000, 'trace')
+  assert.equal(l.readFailure?.reason, 'connect ETIMEDOUT', '읽기 실패가 남아 있다')
+  assert.equal(l.cursorStall?.reason, 'one timestamp holds more rows than a page')
+  assert.equal(l.readFailure?.stream, 'inventory')
+  assert.equal(l.cursorStall?.stream, 'trace', '어느 표가 막혔나가 조치의 절반이다')
+})
+
+test('각자 지워진다 — 하나가 풀렸다고 다른 하나를 지우지 않는다', () => {
+  const l = newIngestLedger()
+  recordReadFailure(l, 'ETIMEDOUT', T0)
+  recordCursorStall(l, 'cursor cannot advance', T0)
+  clearReadFailure(l)
+  assert.equal(l.readFailure, undefined, '다시 닿았다')
+  assert.ok(l.cursorStall, '그렇다고 커서가 넘어간 것은 아니다')
+  clearCursorStall(l)
+  assert.equal(l.cursorStall, undefined, '넘어갔으면 지운다')
+})
+
+test('「몇 번·언제부터」를 정체 쪽도 든다 — 한 번 밀린 것과 사흘째는 다르다', () => {
+  const l = newIngestLedger()
+  recordCursorStall(l, 'stuck at 2026-04-15T01:49', T0)
+  recordCursorStall(l, 'stuck at 2026-04-15T01:49', T0 + 600_000)
+  recordCursorStall(l, 'stuck at 2026-04-15T01:49', T0 + 1_200_000)
+  assert.equal(l.cursorStall?.consecutive, 3)
+  assert.equal(l.cursorStall?.sinceMs, T0, '처음 막힌 시각을 지킨다')
+  assert.equal(l.cursorStall?.lastAtMs, T0 + 1_200_000)
+  /* 넘어간 뒤 다시 막히면 **새 정체**다 — 옛 시작 시각을 물려받지 않는다. */
+  clearCursorStall(l)
+  recordCursorStall(l, 'stuck again', T0 + 3_600_000)
+  assert.equal(l.cursorStall?.consecutive, 1)
+  assert.equal(l.cursorStall?.sinceMs, T0 + 3_600_000)
+})
+
+test('뷰로 나간다 — **유입이 없는 갈래에서도**', () => {
+  /*
+   * ★ 여기가 가장 조용해지기 쉬운 자리다. 커서가 막히면 유입이 0이므로 장부가 「빈 장부」 갈래를
+   * 지나고, 그 갈래에서 이 값을 떨어뜨리면 **정체가 실제로 일어나는 바로 그 상황에서** 침묵한다.
+   * `unhandled` 를 스냅샷이 떨어뜨려 정합성 검사가 영원히 조용했던 것과 같은 부류다.
+   */
+  const l = newIngestLedger()
+  recordCursorStall(l, 'one timestamp holds more rows than a page', T0, 'trace')
+  const v = ingestHealth(l, 'attached', undefined, T0 + 60_000)
+  assert.ok(v.cursorStall, '유입이 없어도 뷰에 실린다')
+  assert.equal(v.cursorStall?.consecutive, 1)
+  assert.equal(v.cursorStall?.since, new Date(T0).toISOString())
+  assert.equal(v.cursorStall?.stream, 'trace')
+  assert.equal(v.readFailure, undefined, '닿지 못한 것은 아니다 — 섞이지 않는다')
+})
+
+test('유입이 있는 갈래에서도 나간다 — 두 갈래를 다 채운다', () => {
+  /* 갈래가 둘인 함수에서 한쪽만 채우는 실수를 이 저장소가 이미 겪었다. */
+  const l = newIngestLedger()
+  recordIngest(l, 5, [], T0)
+  recordCursorStall(l, 'cursor cannot advance', T0 + 1000, 'lot')
+  const v = ingestHealth(l, 'attached', undefined, T0 + 2000)
+  assert.equal(v.total.offered, 5, '유입이 있는 갈래다 — 빈 비교로 통과하지 않는다')
+  assert.equal(v.cursorStall?.stream, 'lot')
+})
+
+test('막히지 않았으면 그 칸을 만들지 않는다 — 빈 값이 「막혔다」로 읽히지 않게', () => {
+  const l = newIngestLedger()
+  recordIngest(l, 3, [], T0)
+  assert.equal(ingestHealth(l, 'attached', undefined, T0 + 1000).cursorStall, undefined)
+})
+
+test('두 사실이 같은 문으로 나가지 않는다 — 배선을 소스로 확인한다', () => {
+  /*
+   * 장부만 시험하면 **호스트가 여전히 읽기 실패 문으로 보내도** 초록이다. 실제로 그랬던 것이 이 결함의
+   * 시작이었다.
+   */
+  const src = readFileSync(join(import.meta.dirname, '..', 'server', 'service', 'reference', 'reference-live.ts'), 'utf8')
+  const code = src.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/(^|[^:])\/\/.*$/gm, '$1')
+  assert.match(code, /onCursorStall:/, '어댑터의 정체 통로를 잇는다')
+  assert.match(code, /recordIngestCursorStall/, '정체는 정체 장부로 간다')
+  /* 그리고 그 문구가 「닿지 못한다」와 달라야 한다 — 같은 말이면 화면이 여전히 반대로 안내한다. */
+  const at = code.indexOf('onCursorStall:')
+  const body = code.slice(at, at + 900)
+  assert.match(body, /cursor cannot advance/, '무엇이 막혔는지 말한다')
+  assert.match(body, /Waiting will not clear this/, '기다림이 답이 아니라고 말한다')
+  assert.doesNotMatch(body, /recordIngestReadFailure/, '읽기 실패 장부로 보내지 않는다')
+  /* 재부착의 자격(`status`)은 여기서도 건드리지 않는다 — 2026-08-23 에 되돌린 그 규율. */
+  assert.doesNotMatch(body, /status:/, '정체가 피드를 영구히 끄지 않는다')
+})

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`)
   }
 })