@things-factory/headless-twin 10.0.18 → 10.1.0

package/test/ingest-reconcile-four-ways.test.ts

@@ -0,0 +1,97 @@
+/*
+ * ★ **셈이 닫혀야 한다** — 두 갈래로는 큰 수가 「사라졌다」로 떠 있게 된다.
+ *
+ * ── 실측 (2026-09-05, 인티그레이션·plant 레인) ─────────────────────────────
+ * plant 아웃박스와 저널을 손으로 맞춰 보니 정확히 닫혔다.
+ *
+ *   나간 것 157 = 앉은 것 46 + 거절 2 + 어휘 1 + 되풀이 108
+ *
+ * 되풀이 108은 하네스가 같은 실적을 같은 시각으로 다시 보낸 것이고 **합친 것이 옳은 거동**이다.
+ * 어휘 1은 저널에 안 가는 것이 옳다(시각축이 없다).
+ *
+ * ── 왜 두 갈래로는 안 되나 ────────────────────────────────────────────────
+ *   두 갈래   157 − 46 − 2 = 109 「설명 못 함」
+ *   네 갈래   157 − 46 − 2 − 108 − 1 = 0
+ *
+ * **109 를 「사라졌다」로 내면 그날부터 아무도 그 수를 안 본다.** 늘 큰 수가 떠 있으면 진짜로 하나
+ * 사라진 날을 못 본다 — 오늘 이 저장소에서 「늘 참인 경고는 벽지가 된다」로 여러 번 나온 것이다.
+ *
+ * ── 그리고 되풀이 108은 잰 값이 아니었다 ──────────────────────────────────
+ * 뺄셈으로만 구할 수 있었다. 어휘 항이 없어서다. 그 뺄셈을 코드가 하려면 넷이 다 있어야 한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  newIngestLedger,
+  recordIngest,
+  recordDuplicates,
+  recordVocabulary,
+  recordJournalWrite
+} from '../server/engine/ingest-health.js'
+
+const T0 = 1_757_000_000_000
+
+test('★ 넷을 다 세면 셈이 0으로 닫힌다 — 실측한 그 수로', () => {
+  const ledger = newIngestLedger()
+
+  /* 나간 것 157 · 거절 2 */
+  recordIngest(ledger, 157, [{ errors: ['x'] }, { errors: ['y'] }], T0)
+  /* 저널에 앉은 것 46 */
+  recordJournalWrite(ledger, 46, T0)
+  /* 합친 것 108 */
+  recordDuplicates(ledger, 108, T0)
+  /* 저널에 안 가는 어휘 1 */
+  recordVocabulary(ledger, 1)
+
+  const w = ledger.window
+  const unexplained = w.offered - w.rows - w.rejected - ledger.duplicates - w.vocabulary
+
+  assert.equal(unexplained, 0, `설명 못 한 것이 ${unexplained} 남았다 — 셈이 안 닫힌다`)
+})
+
+test('★ 어휘 항이 없으면 그 수가 「사라졌다」로 남는다 — 이 항의 존재 이유', () => {
+  const ledger = newIngestLedger()
+  recordIngest(ledger, 20, undefined, T0)
+  recordJournalWrite(ledger, 17, T0)
+  recordVocabulary(ledger, 1)
+
+  const w = ledger.window
+  /* 어휘를 안 빼면 셋이 빈 것으로 보인다 — 실제로 사라진 것은 둘이다. */
+  assert.equal(w.offered - w.rows, 3, '실측 상황을 못 만들고 있다')
+  assert.equal(w.offered - w.rows - w.vocabulary, 2, '어휘를 빼도 수가 안 맞는다')
+})
+
+test('★ 어휘는 저널 수에 안 들어간다 — 두 번 세면 셈이 음수가 된다', () => {
+  const ledger = newIngestLedger()
+  recordIngest(ledger, 1, undefined, T0)
+  recordVocabulary(ledger, 1)
+
+  assert.equal(ledger.window.rows, 0, '어휘가 저널 수에 섞였다')
+  assert.equal(ledger.window.vocabulary, 1)
+})
+
+test('★ 창이 갈리면 각 창이 자기 어휘를 든다 — 누적으로 비교하면 안 된다', () => {
+  /*
+   * 인티그레이션 레인이 짚은 것: `mes-line-a` 가 커서 48 · 저널 11 인데 결함이 아니다(그 사이
+   * 저널을 비웠다). **창 단위로** 맞춰야 한다.
+   */
+  const ledger = newIngestLedger()
+  recordIngest(ledger, 5, undefined, T0)
+  recordVocabulary(ledger, 2)
+  assert.equal(ledger.window.vocabulary, 2)
+
+  /* 창을 넘긴다 — 새 창은 0에서 시작한다. */
+  recordIngest(ledger, 5, undefined, T0 + 700_000)
+  assert.equal(ledger.window.vocabulary, 0, '새 창이 앞 창의 어휘를 물고 왔다')
+  assert.equal(ledger.vocabulary, 2, '누적은 남아야 한다')
+})
+
+test('★ 이 검사가 실제로 무언가를 잰다 — 견준 것이 0이면 빨강', () => {
+  const ledger = newIngestLedger()
+  assert.equal(ledger.window.vocabulary, 0, '새 창에 그 항이 없다')
+  recordVocabulary(ledger, 0)
+  assert.equal(ledger.vocabulary, 0, '0을 세었다 — 모르면 안 적는다')
+  recordVocabulary(ledger, -3)
+  assert.equal(ledger.vocabulary, 0, '음수를 세었다')
+})

package/test/ingest-rules-header.test.ts

@@ -0,0 +1,100 @@
+/*
+ * 트윈의 고정 유입 규칙이 **표준 헤더 필드를 세 갈래 모두에서** 통과시키나.
+ *
+ * ── 왜 필요한가 (2026-09-07) ────────────────────────────────────────────────
+ * 같은 결함이 이 저장소에서 네 번 났고, 네 번 다 **층이 달랐다.**
+ *
+ * ```
+ * 1  EpcisHeaderOptions 에 칸이 없다        objectEvent 만 자기 인자로 갖고 있었다
+ * 2  매핑 스펙에 칸이 없다                  커넥터가 선언할 자리가 없었다
+ * 3  이 파일의 규칙 셋에 칸이 없다           선언해도 여기서 사라졌다
+ * 4  받는 쪽                                — 이건 처음부터 서 있었다
+ * ```
+ *
+ * 세 층이 각각 새는 자리였고, **아래 두 층을 고친 뒤에도 위층에서 계속 사라졌다.** 계약을 열고
+ * 「됐다」고 한 것이 아니라 인티그레이션 레인이 이 규칙 그대로 `mapRecord` 를 돌려 봐서 찾았다.
+ *
+ * 그래서 이 시험은 **계약이 아니라 이 파일의 규칙**을 돌린다. 계약 쪽 시험이 초록이어도 여기서
+ * 사라질 수 있다는 것이 오늘 실제로 일어난 일이다.
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import { mapRecordChecked } from '@operato/ops-contract'
+
+import { canonicalRulesForTest } from '../server/engine/canonical-ingest.js'
+
+const AT = '2026-09-07T02:00:00.000Z'
+
+/** 세 갈래가 각자 성립하는 최소 레코드 — 헤더 값은 같은 것을 싣는다. */
+const HEADER = {
+  bizStep: 'urn:epcglobal:cbv:bizstep:storing',
+  disposition: 'urn:epcglobal:cbv:disp:in_progress',
+  readPoint: 'urn:epc:id:sgln:0614141.00001.0',
+  bizLocation: 'urn:epc:id:sgln:0614141.00002.0',
+  bizTransactionList: [{ type: 'urn:epcglobal:cbv:btt:po', bizTransaction: 'urn:epcglobal:cbv:bt:0614141:order-33' }],
+  errorDeclaration: { declarationTime: AT, reason: 'urn:epcglobal:cbv:er:incorrect_data' }
+}
+
+const RECORDS: { sourceType: string; record: Record<string, unknown> }[] = [
+  { sourceType: 'twin', record: { ...HEADER, action: 'OBSERVE', epc: 'urn:epc:id:sgtin:0614141.107346.2018' } },
+  {
+    sourceType: 'twin-transformation',
+    record: {
+      ...HEADER,
+      inputEPCList: ['urn:epc:id:sgtin:0614141.107346.1000'],
+      outputEPCList: ['urn:epc:id:sgtin:0614141.107346.2000'],
+      transformationID: 'urn:uuid:11111111-2222-3333-4444-555555555555'
+    }
+  },
+  {
+    sourceType: 'twin-aggregation',
+    record: { ...HEADER, action: 'ADD', parentID: 'urn:epc:id:sscc:0614141.1234567890', childEPCs: ['urn:epc:id:sgtin:0614141.107346.2018'] }
+  }
+]
+
+function mapWith(sourceType: string, record: Record<string, unknown>): any {
+  const rule = canonicalRulesForTest().find(r => r.sourceType === sourceType)
+
+  assert.ok(rule, `${sourceType} 규칙이 없다 — 갈래가 사라졌다`)
+
+  return mapRecordChecked(record as any, rule!.mapping as any, AT)
+}
+
+test('규칙이 셋이다 — 갈래가 줄면 그 사실이 조용히 사라진다', () => {
+  assert.deepEqual(
+    canonicalRulesForTest().map(r => r.sourceType).sort(),
+    ['twin', 'twin-aggregation', 'twin-transformation']
+  )
+})
+
+for (const { sourceType, record } of RECORDS) {
+  test(`${sourceType} 이 오더 참조를 커널까지 넘긴다 — 이 파일에서 사라지던 자리다`, () => {
+    const { event, errors } = mapWith(sourceType, record)
+
+    assert.deepEqual(errors, [], `${sourceType}: 성립하는 레코드인데 오류가 났다`)
+    assert.deepEqual(
+      event.bizTransactionList,
+      HEADER.bizTransactionList,
+      `${sourceType}: 오더 참조가 사라졌다 — 커넥터가 실어도 저널의 biz_transaction 이 빈다`
+    )
+  })
+
+  test(`${sourceType} 이 나머지 헤더 필드도 함께 넘긴다 — 하나만 보면 다음 것이 또 샌다`, () => {
+    const { event } = mapWith(sourceType, record)
+
+    assert.equal(event.bizStep, HEADER.bizStep)
+    assert.equal(event.disposition, HEADER.disposition)
+    assert.equal(event.readPoint?.id, HEADER.readPoint)
+    assert.equal(event.bizLocation?.id, HEADER.bizLocation)
+    assert.equal(event.errorDeclaration?.declarationTime, AT)
+  })
+}
+
+test('오더 참조를 안 실으면 그 칸을 만들지 않는다 — 빈 배열은 「참조가 없다」와 다르다', () => {
+  const { bizTransactionList: _drop, ...bare } = RECORDS[0].record
+  const { event, errors } = mapWith('twin', bare)
+
+  assert.deepEqual(errors, [])
+  assert.equal('bizTransactionList' in event, false)
+})

package/test/ingest-window-rolls-unobserved.test.ts

@@ -0,0 +1,72 @@
+/*
+ * ★ **보는 사람이 없어도 창이 닫힌다** — 아무도 안 보는 트윈일수록 기록이 없었다.
+ *
+ * ── 실측 (2026-09-05) ──────────────────────────────────────────────────────
+ *   mes-miratek   사실 46건 · 62분에 흩어짐   창  1개
+ *   mes-line-a    사실 11건                   창 48개
+ *
+ * **사실 수와 창 수가 거꾸로다.** 창은 「다음 사건이 왔을 때」와 「누가 물어볼 때」만 굴렀고,
+ * `ingestHealthOf()` 가 굴리는 쪽이 실제로 창을 만들고 있었다 — 점검표·화면이 계속 묻는 트윈만
+ * 기록이 쌓였다.
+ *
+ * 그래서 **아무도 안 보는 트윈일수록 기록이 없었다.** 사실이 조용히 사라지는 것을 잡으려고 만든
+ * 장부가 정확히 그 반대로 돌았다. 실제로 137봉투가 장부 없이 지나갔다(인티그레이션 레인 실측).
+ *
+ * ── 왜 주기인가 ────────────────────────────────────────────────────────────
+ * 창이 닫히는 이유는 **시간이 지난 것**이다. 사건도 질의도 그것을 알려 주는 신호일 뿐이고 둘 다
+ * 안 올 수 있다. 시간은 늘 지나므로 주기가 그 사실에 맞는 신호다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { INGEST_WINDOW_MS, newIngestLedger, recordJournalWrite, rollIngestWindow } from '../server/engine/ingest-health.js'
+
+const T0 = 1_757_000_000_000
+
+test('★ 사건도 질의도 없이 시간만 지나면 창이 닫힌다', () => {
+  const ledger = newIngestLedger()
+  const closed: any[] = []
+
+  /* 사실 하나가 들어와 창이 열린다. */
+  recordJournalWrite(ledger, 1, T0, w => closed.push(w))
+  assert.equal(closed.length, 0, '열리자마자 닫히면 안 된다')
+
+  /* 그 뒤로 아무 일도 없다 — 주기만 온다. */
+  rollIngestWindow(ledger, T0 + INGEST_WINDOW_MS + 1, INGEST_WINDOW_MS, w => closed.push(w))
+
+  assert.equal(closed.length, 1, '시간이 지났는데 창이 안 닫혔다 — 기록이 안 남는다')
+  assert.equal(closed[0].rows, 1, '닫힌 창이 그 사실을 안 들었다')
+})
+
+test('★ 창 길이 전에는 안 닫는다 — 주기가 창을 잘게 쪼개면 안 된다', () => {
+  const ledger = newIngestLedger()
+  const closed: any[] = []
+  recordJournalWrite(ledger, 1, T0)
+
+  /* 주기(30초)가 창 길이(10분)보다 짧다 — 여러 번 와도 안 닫혀야 한다. */
+  for (let i = 1; i <= 10; i++) rollIngestWindow(ledger, T0 + i * 30_000, INGEST_WINDOW_MS, w => closed.push(w))
+
+  assert.equal(closed.length, 0, `주기가 창을 ${closed.length}개로 쪼갰다`)
+})
+
+test('★ 조용한 구간도 창으로 남는다 — expected-quiet 판정이 그 기록 위에 선다', () => {
+  /*
+   * 사실이 하나도 안 온 구간이 표에 남아야 「조용한 것이 정상인가」를 판정할 수 있다. 그 구간이
+   * 아예 기록되지 않으면 조용함과 기록 없음이 구별되지 않는다.
+   */
+  const ledger = newIngestLedger()
+  const closed: any[] = []
+  recordJournalWrite(ledger, 1, T0, w => closed.push(w))
+
+  /* 두 창을 통째로 건너뛴다 — 그 사이 아무 사실도 없었다. */
+  rollIngestWindow(ledger, T0 + INGEST_WINDOW_MS * 2 + 1, INGEST_WINDOW_MS, w => closed.push(w))
+
+  assert.ok(closed.length >= 1, '건너뛴 구간이 하나도 안 남았다')
+})
+
+test('★ 이 검사가 실제로 무언가를 잰다 — 견준 것이 0이면 빨강', () => {
+  assert.ok(INGEST_WINDOW_MS > 0, `창 길이가 ${INGEST_WINDOW_MS} 다`)
+  const ledger = newIngestLedger()
+  recordJournalWrite(ledger, 3, T0)
+  assert.equal(ledger.window.rows, 3, '장부가 사실을 안 세고 있다 — 이 검사가 아무것도 안 잰다')
+})

package/test/intake-mapping-parity.test.ts

@@ -0,0 +1,175 @@
+/*
+ * ★ **접수 타입에 있는 칸은 매핑도 옮긴다** — 문턱에서 조용히 버려지던 자리.
+ *
+ * ── 오늘 이 부류가 일곱 번이었다 (2026-09-04) ──────────────────────────────
+ *   ActuationAck 이 세 칸을 버린다고 말한다     타입과 값 사이
+ *   save 가 새 칸을 안 쓴다                    칸과 쓰는 길
+ *   질의가 noteNext 를 안 낸다                 저장과 화면 사이
+ *   커넥터가 등급 셋을 읽어 놓고 버린다          원본 쪽
+ *   homeLocation vs homeLocationId            낱말 하나
+ *   equipmentClassIds 칸이 접수면에 없다        ← 이 검사가 막는 것
+ *   materialActual 안쪽을 안 본다               검사가 얕다
+ *
+ * **일곱 다 오류가 안 나서** 검사로만 잡혔다.
+ *
+ * ── 이 자리가 특히 조용하다 ─────────────────────────────────────────────────
+ * 접수 타입(`RefEquipment` …)에 칸이 있어도 매핑 함수가 안 옮기면 **원본이 채운 값이 문턱에서
+ * 사라진다.** 타입만 봐서는 안 보인다 — 타입은 「받는다」고 말하고 있으니까.
+ *
+ * 실제로 그렇게 났다: 설비 22대에 등급을 다 채웠는데 등급 목록만 서고 소속은 아무도 없었다.
+ * 화면에서 등급을 골라도 설비가 안 나왔고, 거절도 경고도 없었다.
+ *
+ * ── 왜 원문을 읽나 ──────────────────────────────────────────────────────────
+ * 매핑은 객체 리터럴이라 런타임에 「무엇을 옮기나」를 물을 수 없다(입력을 다 채워 넣어 답을 보는
+ * 방법이 있지만, 그러면 선택 필드마다 픽스처를 손으로 적어야 하고 그 손이 바로 빠뜨리는 자리다).
+ * 원문에서 읽으면 **이름을 손으로 적지 않아** 타입이 늘 때 검사가 함께 따라간다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+
+const SRC = readFileSync(new URL('../server/service/reference/reference-master.ts', import.meta.url), 'utf8')
+  .replace(/\/\*[\s\S]*?\*\//g, '')
+  .replace(/\/\/[^\n]*/g, '')
+
+/** 접수 타입 하나의 칸 이름들 — `export interface X { … }` 의 깊이 1 필드. */
+function intakeFields(name: string): string[] {
+  const start = SRC.indexOf(`export interface ${name} {`)
+  assert.ok(start >= 0, `접수 타입을 못 찾았다: ${name} — 이 검사가 따라가야 한다`)
+  const body = SRC.slice(SRC.indexOf('{', start))
+  const end = body.indexOf('\n}')
+  assert.ok(end > 0, `${name} 의 끝을 못 찾았다`)
+  return [...new Set([...body.slice(0, end).matchAll(/^\s{2}([a-zA-Z][\w]*)\??:/gm)].map(m => m[1]))]
+}
+
+/**
+ * 매핑 함수가 **읽는** 칸들 — `e.foo` · `a.foo` 처럼 원본 줄에서 꺼내는 이름.
+ *
+ * 옮긴 뒤 이름이 바뀌는 것도 있다(`homeLocationId → homeLocation`). 그래서 「나가는 이름」이 아니라
+ * **「읽는 이름」**을 센다 — 읽지 않으면 옮길 수도 없다.
+ */
+function readFields(varName: string): string[] {
+  return [...new Set([...SRC.matchAll(new RegExp(`\\b${varName}\\.([a-zA-Z][\\w]*)`, 'g'))].map(m => m[1]))]
+}
+
+/**
+ * 일부러 안 옮기는 칸 — 이유와 함께.
+ *
+ * 비어 있는 것이 정상이 아니다: 접수면이 받아 두고 커널에 안 넘기는 값이 있으면 **왜 받는지**가
+ * 적혀 있어야 한다. 안 적으면 다음 사람이 「원래 그런가 보다」로 넘긴다.
+ */
+const NOT_MAPPED: Record<string, { fields: string[]; why: string }> = {
+  RefEquipment: {
+    fields: [],
+    why: ''
+  },
+  RefAsset: {
+    fields: [],
+    why: ''
+  },
+  RefPerson: {
+    fields: [],
+    why: ''
+  }
+}
+
+const CASES = [
+  { intake: 'RefEquipment', reads: 'e' },
+  { intake: 'RefAsset', reads: 'a' },
+  { intake: 'RefPerson', reads: 'p' }
+] as const
+
+test('★ 접수 타입의 칸을 매핑이 다 읽는다 — 안 읽으면 원본이 채운 값이 문턱에서 사라진다', () => {
+  const dropped: string[] = []
+
+  for (const c of CASES) {
+    const excused = new Set(NOT_MAPPED[c.intake]?.fields ?? [])
+    const read = new Set(readFields(c.reads))
+
+    for (const f of intakeFields(c.intake)) {
+      if (!read.has(f) && !excused.has(f)) dropped.push(`${c.intake}.${f}`)
+    }
+  }
+
+  assert.deepEqual(
+    dropped,
+    [],
+    '접수 타입은 받는다고 말하는데 매핑이 안 읽는다. 원본이 채운 값이 조용히 사라진다:\n  ' +
+      dropped.join('\n  ') +
+      '\n매핑에 넣거나, 일부러 안 넘긴다면 NOT_MAPPED 에 이유를 적는다.'
+  )
+})
+
+test('★ 등급 소속 셋이 다 접수면을 지난다 — 이름으로 못 박는다', () => {
+  /*
+   * 위 검사는 목록 대조라 예외 표에 올리면 통과한다. 이 셋은 **소속이 없으면 등급으로 부르는
+   * 요구가 채워지지 않는** 자리여서 예외가 될 수 없다.
+   */
+  for (const [type, field, reads] of [
+    ['RefEquipment', 'equipmentClassIds', 'e'],
+    ['RefAsset', 'assetClassIds', 'a'],
+    ['RefPerson', 'personnelClassIds', 'p']
+  ] as const) {
+    assert.ok(intakeFields(type).includes(field), `${type} 에 ${field} 칸이 없다`)
+    assert.ok(readFields(reads).includes(field), `매핑이 ${type}.${field} 를 안 읽는다 — 소속이 문턱에서 사라진다`)
+  }
+})
+
+test('★ 사람도 정체성 자리를 갖는다 — 그리고 그 자리는 개인정보가 아니다', () => {
+  /*
+   * ── 왜 열었나 (2026-09-05, 인티그레이션 레인이 물음) ────────────────────────
+   * 설비에서 이 자리를 만든 이유가 사람에게도 그대로 걸린다 — 지역 이름은 그 현장 안에서만
+   * 고유하다. `E-1001` 이 다른 공장에도 있으면 여러 현장을 함께 보는 순간 한쪽이 사라진다.
+   *
+   * ── 왜 이 검사에 규약을 함께 적나 ──────────────────────────────────────────
+   * 설비와 사람이 갈리는 자리가 있다. 사람의 「전역에서 고유한 값」은 사원번호·카드번호처럼
+   * **그 사람에 관한 사실**이고, 저널은 되풀이 읽히고 미러로 복제되고 구독으로 방송된다 —
+   * 한 번 들어가면 지워지지 않는다.
+   *
+   * 이 칸이 요구하는 것은 **현장을 앞에 붙여 전역에서 고유해진 이름**이다(`objectUri` 가 만든다).
+   * 그 규약이 주석에만 있으면 다음 커넥터가 카드번호를 넣는다 — 그러니 소스에 그 문장이 실제로
+   * 있는지를 검사가 지킨다.
+   */
+  assert.ok(intakeFields('RefPerson').includes('identity'), 'RefPerson 에 identity 칸이 없다')
+  assert.ok(readFields('p').includes('identity'), '매핑이 사람의 identity 를 안 읽는다')
+
+  /* 규약이 글로 남아 있나 — 지우면 이 줄이 빨개진다. */
+  const raw = readFileSync(new URL('../server/service/reference/reference-master.ts', import.meta.url), 'utf8')
+  const start = raw.indexOf('export interface RefPerson')
+  const personDoc = raw.slice(start, raw.indexOf('\n}', start))
+  assert.ok(personDoc.includes('개인정보'), '개인정보를 넣지 않는다는 규약이 사라졌다')
+  assert.ok(personDoc.includes('objectUri'), '무엇을 넣어야 하는지(이름공간 아래 식별자)가 사라졌다')
+})
+
+test('★ 정체성 낱말이 세 자리에서 같다 — 마스터가 내는 이름과 접수면이 받는 이름', () => {
+  /*
+   * 설비는 `identity` 로 바꿨는데 자산은 `gs1Id` 로 남아 있었다. 마스터는 둘 다 `identity` 로
+   * 내므로 자산 쪽은 **원본이 채우는 순간 조용히 사라졌다** — 값이 다 비어 있어 아직 잃은 것은
+   * 없었다(인티그레이션 레인 실측).
+   *
+   * 자리(`RefLocation`)는 `gs1Id` 가 맞다 — 거기는 실제로 SGLN 이 온다.
+   */
+  assert.ok(intakeFields('RefEquipment').includes('identity'), '설비 정체성 이름이 바뀌었다')
+  assert.ok(intakeFields('RefAsset').includes('identity'), '자산이 아직 마스터와 다른 이름을 쓴다')
+  assert.ok(!intakeFields('RefAsset').includes('gs1Id'), '자산에 옛 이름이 남아 있다')
+  assert.ok(intakeFields('RefLocation').includes('gs1Id'), '자리는 SGLN 이 오므로 그 이름이 맞다')
+})
+
+test('★ 이 검사가 실제로 무언가를 잰다 — 견준 것이 0이면 빨강', () => {
+  /*
+   * 정규식이 모양을 못 따라가면 목록이 비고, 그러면 위 검사가 **초록인데 아무것도 안 재는 상태**가
+   * 된다. 오늘 이 저장소에서 그 부류를 여러 번 잡았다.
+   */
+  for (const c of CASES) {
+    const fields = intakeFields(c.intake)
+    const read = readFields(c.reads)
+    assert.ok(fields.length > 5, `${c.intake} 칸을 ${fields.length}개만 읽었다`)
+    assert.ok(read.length > 5, `${c.reads}.* 를 ${read.length}개만 읽었다`)
+  }
+
+  /* 이유 없는 예외는 예외가 아니다 — 비어 있는 항목은 예외가 아니라 자리표시다. */
+  for (const [type, e] of Object.entries(NOT_MAPPED)) {
+    if (!e.fields.length) continue
+    assert.ok(e.why?.trim(), `${type} 의 예외에 이유가 없다`)
+  }
+})

package/test/live-cadence.test.ts

@@ -0,0 +1,170 @@
+/*
+ * ★ **원천마다 시간의 결이 다르다** — 밤마다 나던 거짓 빨강의 나머지 반쪽.
+ *
+ * 판정은 이미 두 값을 받을 수 있다(`syncVerdictOf` 의 `expectedSilenceMs`·`quietNow`). 없던 것은
+ * **원천이 그것을 말할 자리**였다. 인티그레이션 레인이 다섯을 재 왔다.
+ *
+ *   ppms 발전      일몰에 멈춘다 — 두 사이트가 같은 분 19:25 에 함께
+ *   ppms 계측      밤에도 온다 · 15분마다
+ *   ppms 가격      화·목만 거래된다 · 그 날 하루 한 번
+ *   plant         근무시간 창 · 훅이라 「보내면 온다」
+ *   chef          조업시간 창 · 같음
+ *
+ * 셋이 다 다르다 — 해에 매인 것, 사람 근무에 매인 것, 거래일에 매인 것. 그런데 **두 축으로
+ * 덮인다**: 「지금이 활동 시각인가」와 「그 안에서 얼마나 뜸한가」.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { cadenceOf, ingestExpectation, type LiveCadence } from '../server/service/reference/live-cadence.js'
+
+const NOW = 1_800_000_000_000
+
+/* ── 축을 찾는다 ──────────────────────────────────────────────────────────── */
+
+test('★ 선언한 축을 찾는다', () => {
+  const cadences: LiveCadence[] = [
+    { axis: 'equipment.status', windowKind: 'daylight' },
+    { axis: 'quality.output', expectedSilenceMs: 900_000 }
+  ]
+
+  assert.equal(cadenceOf(cadences, 'quality.output')?.expectedSilenceMs, 900_000)
+  assert.equal(cadenceOf(cadences, 'equipment.status')?.windowKind, 'daylight')
+})
+
+test('★ 선언하지 않은 축은 없다고 답한다 — 옛 거동으로 견주게', () => {
+  assert.equal(cadenceOf([{ axis: 'quality.output' }], 'order.status'), undefined)
+  assert.equal(cadenceOf(undefined, 'quality.output'), undefined)
+})
+
+/* ── 판정에 넘길 두 값으로 옮긴다 ───────────────────────────────────────── */
+
+test('★ 선언이 없으면 아무것도 답하지 않는다 — 「모른다」를 「안 와도 된다」로 접지 않는다', () => {
+  /*
+   * 여기서 `quietNow: true` 를 내면 **선언 안 한 원천이 전부 조용해진다.** 정말 끊긴 것도
+   * 조용해지고, 그러면 이 축을 만든 목적을 잃는다.
+   */
+  assert.deepEqual(ingestExpectation(undefined, { nowMs: NOW }), {})
+})
+
+test('★ 15분마다 긷는 원천 — 주기만 넘긴다', () => {
+  const out = ingestExpectation({ axis: 'quality.output', expectedSilenceMs: 900_000 }, { nowMs: NOW })
+
+  assert.equal(out.expectedSilenceMs, 900_000)
+  assert.equal(out.quietNow, undefined, '창을 선언하지 않았는데 시각을 단언했다')
+})
+
+test('0이나 음수 주기는 선언이 아니다', () => {
+  for (const bad of [0, -1, NaN]) {
+    const out = ingestExpectation({ axis: 'a', expectedSilenceMs: bad }, { nowMs: NOW })
+    assert.equal(out.expectedSilenceMs, undefined, `${bad} 를 주기로 받았다`)
+  }
+})
+
+/* ── 「보내면 온다」 ──────────────────────────────────────────────────────── */
+
+test('★ 훅으로 미는 축은 침묵으로 판정하지 않는다 — plant 가 그렇다', () => {
+  /*
+   * 보낼 것이 없으면 안 보내는 것이 정상이다. 「주기가 없다」와 「모른다」를 가르는 값이다.
+   */
+  const out = ingestExpectation({ axis: 'order.status', pushed: true }, { nowMs: NOW })
+
+  assert.equal(out.quietNow, true)
+})
+
+test('★ 미는 축은 창 판정을 기다리지 않는다 — 판정 수단이 없어도 답한다', () => {
+  const out = ingestExpectation(
+    { axis: 'order.status', pushed: true, window: [{ id: 'day', entryType: 'production', startTime: '09:00', endTime: '18:00' }] },
+    { nowMs: NOW } /* inWindow 를 주지 않았다 */
+  )
+
+  assert.equal(out.quietNow, true)
+})
+
+/* ── 창 ──────────────────────────────────────────────────────────────────── */
+
+test('★ 활동 시각 안이면 조용할 때가 아니다', () => {
+  const out = ingestExpectation(
+    { axis: 'quality.output', window: [{ id: 'day', entryType: 'production', startTime: '09:00', endTime: '18:00' }] },
+    { nowMs: NOW, inWindow: () => true }
+  )
+
+  assert.equal(out.quietNow, false)
+})
+
+test('★ 활동 시각 밖이면 조용할 때다', () => {
+  const out = ingestExpectation(
+    { axis: 'quality.output', window: [{ id: 'day', entryType: 'production', startTime: '09:00', endTime: '18:00' }] },
+    { nowMs: NOW, inWindow: () => false }
+  )
+
+  assert.equal(out.quietNow, true)
+})
+
+test('★ 판정 수단을 안 받았으면 시각을 단언하지 않는다 — 지어낸 값을 만들지 않는다', () => {
+  /*
+   * 부르는 쪽이 달력 판정 함수를 주지 않았는데 우리가 「활동 시각이다」로 답하면, 창을 선언한
+   * 원천이 **창이 없는 것과 같아진다.** 그것은 조용한 실패다.
+   */
+  const out = ingestExpectation(
+    { axis: 'quality.output', window: [{ id: 'day', entryType: 'production', startTime: '09:00', endTime: '18:00' }] },
+    { nowMs: NOW }
+  )
+
+  assert.equal(out.quietNow, undefined)
+})
+
+test('빈 창은 창이 아니다', () => {
+  assert.equal(ingestExpectation({ axis: 'a', window: [] }, { nowMs: NOW, inWindow: () => false }).quietNow, undefined)
+})
+
+/* ── 두 축이 함께 온다 ──────────────────────────────────────────────────── */
+
+test('★ 주기와 창을 같이 선언할 수 있다 — 인증서 가격이 그 모양이다', () => {
+  /*
+   * 화·목만 거래되고 그 날 하루 한 번 온다. 「매일 와야 한다」로 재면 주 5일 중 3일이 빨갛고,
+   * 「주 2회」로 재면 이어 쓴 날을 못 본다. 두 축이면 둘 다 답한다.
+   */
+  const out = ingestExpectation(
+    {
+      axis: 'quality.output',
+      expectedSilenceMs: 26 * 3_600_000,
+      window: [
+        { id: 'tue', entryType: 'production', startTime: '00:00', endTime: '23:59' },
+        { id: 'thu', entryType: 'production', startTime: '00:00', endTime: '23:59' }
+      ]
+    },
+    { nowMs: NOW, inWindow: () => false }
+  )
+
+  assert.equal(out.expectedSilenceMs, 26 * 3_600_000)
+  assert.equal(out.quietNow, true, '거래일이 아니면 조용한 것이 정상이다')
+})
+
+/* ── 「해 있는 동안」은 호스트가 채운다 ──────────────────────────────────── */
+
+test('★ 종류만 선언한 것으로는 창 판정을 하지 않는다 — 호스트가 채워야 한다', () => {
+  /*
+   * 커널은 일출·일몰을 계산하지 않는다(굴절·고위도·박명 정의가 다 선택이고, 정하면 방언이다).
+   * 원천은 종류만 말하고, 좌표를 아는 호스트가 날마다 구체적인 구간을 채운다.
+   *
+   * 그러니 `windowKind` 만 있고 `window` 가 비어 있으면 **아직 채워지지 않은 것**이고, 그때
+   * 판정하지 않는다. `false` 로 접으면 태양광이 밤에도 활동 시각인 것이 된다.
+   */
+  const out = ingestExpectation({ axis: 'equipment.status', windowKind: 'daylight' }, { nowMs: NOW, inWindow: () => true })
+
+  assert.equal(out.quietNow, undefined)
+})
+
+test('★ 호스트가 채우면 그것으로 판정한다', () => {
+  const out = ingestExpectation(
+    {
+      axis: 'equipment.status',
+      windowKind: 'daylight',
+      window: [{ id: 'today', entryType: 'production', startTime: '06:12', endTime: '19:25' }]
+    },
+    { nowMs: NOW, inWindow: () => false }
+  )
+
+  assert.equal(out.quietNow, true)
+})