@things-factory/headless-twin 10.0.18 → 10.1.0

package/test/connection-portability-doors.test.ts

@@ -0,0 +1,87 @@
+/*
+ * ★ **연결 이관의 문 셋** — 몸통은 순수 함수이고, 이 검사는 **문이 그 규율을 지키는지** 본다.
+ *
+ * ── 무엇을 옮기나 (사용자와 맞춘 개념, 2026-09-05) ────────────────────────
+ * 옮기는 것은 「붙는 법」이지 「붙은 결과」가 아니다. 마스터·사실·잰 값·비밀값은 안 옮긴다 —
+ * 앞의 셋은 다시 얻을 수 있고, 비밀값은 그 환경의 것이지 셋업이 아니다.
+ *
+ * ── 이 검사가 지키는 것 ────────────────────────────────────────────────────
+ * 문이 몸통의 판단을 **뒤집지 않는지**다. 몸통 시험 19개가 이미 「비밀값이 안 나간다」를 지키는데,
+ * 문이 그것을 되살려 쓰면 그 19개가 아무것도 못 막는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { exportConnections, planImport, SECRET_KEYS } from '../server/service/reference/connection-portability.js'
+
+const row = (over: any = {}) => ({
+  source: 'mes-miratek',
+  system: 'operato-plant',
+  siteName: '미라텍',
+  adapterType: 'operato-plant',
+  connectionConfig: { baseUrl: 'https://plant.example', siteId: 'mes-miratek', token: 'SECRET-VALUE', hookSecret: 'ALSO-SECRET' },
+  ...over
+})
+
+test('★ 비밀값이 꾸러미에 안 나간다 — 이름만 나간다', () => {
+  const b = exportConnections([row()], { at: '2026-09-05T00:00:00.000Z' })
+  const text = JSON.stringify(b)
+
+  assert.ok(!text.includes('SECRET-VALUE'), '토큰이 꾸러미에 실렸다')
+  assert.ok(!text.includes('ALSO-SECRET'), '훅 비밀값이 꾸러미에 실렸다')
+  assert.deepEqual(b.connections[0].secretsRequired.sort(), ['hookSecret', 'token'], '무엇을 채워야 하는지 말하지 않는다')
+})
+
+test('★ 선언은 나간다 — 그것이 옮기려는 것이다', () => {
+  const b = exportConnections([row()], { at: '2026-09-05T00:00:00.000Z' })
+  const c = b.connections[0]
+
+  assert.equal(c.adapterType, 'operato-plant')
+  assert.equal(c.config.baseUrl, 'https://plant.example')
+  assert.equal(c.config.siteId, 'mes-miratek')
+})
+
+test('★ 새 비밀 칸도 기본으로 안 나간다 — 이름 규칙으로 거른다', () => {
+  /*
+   * 비밀 칸이 하나 늘 때 이 목록을 안 고치면 그 값이 파일로 나간다. 그래서 규칙이 이름이고,
+   * 그 규칙이 지금 무엇을 아는지 값으로 못 박는다.
+   */
+  assert.ok(SECRET_KEYS.includes('token' as any))
+  assert.ok(SECRET_KEYS.includes('hookSecret' as any))
+  assert.ok(SECRET_KEYS.includes('intakeSecret' as any))
+  assert.ok(SECRET_KEYS.length >= 4, `비밀 칸 이름을 ${SECRET_KEYS.length}개만 안다`)
+})
+
+test('★ 없는 비밀값을 지어내지 않는다 — 이름을 대고 사람에게 넘긴다', () => {
+  const b = exportConnections([row()], { at: '2026-09-05T00:00:00.000Z' })
+  /* 이 환경에는 그 비밀값이 없다. */
+  const plan = planImport(b, [], () => false)
+
+  const needs = plan.needsHuman.find(n => n.source === 'mes-miratek')
+  assert.ok(needs, '사람이 채울 것을 말하지 않는다')
+  assert.deepEqual(needs!.keys.sort(), ['hookSecret', 'token'])
+})
+
+test('★ 이미 있는 연결의 비밀값을 꾸러미가 안 지운다', () => {
+  const b = exportConnections([row()], { at: '2026-09-05T00:00:00.000Z' })
+  const existing = [{ source: 'mes-miratek', connectionConfig: { token: 'LIVE-TOKEN' } }]
+  const plan = planImport(b, existing, () => false)
+
+  const a = plan.actions.find(x => (x as any).connection?.source === 'mes-miratek') as any
+  assert.equal(a?.action, 'update', `갱신이 아니라 ${a?.action} 이다`)
+  assert.ok(a.keptSecrets?.includes('token'), '이미 있는 토큰을 지킨다고 말하지 않는다')
+})
+
+test('★ 꾸러미가 아닌 것을 받으면 아무것도 하지 않는다', () => {
+  for (const bad of [null, {}, { kind: 'something-else' }, 'text']) {
+    const plan = planImport(bad, [], () => false)
+    assert.equal(plan.actions.length, 0, `${JSON.stringify(bad)} 로 무언가를 하려 했다`)
+    assert.ok(plan.errors.length, '왜 안 되는지 말하지 않는다')
+  }
+})
+
+test('★ 이 검사가 실제로 무언가를 잰다 — 견준 것이 0이면 빨강', () => {
+  const b = exportConnections([row()], { at: '2026-09-05T00:00:00.000Z' })
+  assert.equal(b.connections.length, 1, '꾸러미가 비었다 — 이 검사가 아무것도 안 잰다')
+  assert.ok(planImport(b, [], () => true).actions.length > 0, '계획이 비었다')
+})

package/test/connector-capability-declaration.test.ts

@@ -50,19 +50,69 @@ test('★ 라이브를 구현하고 선언하지 않으면 말해 준다 — 이
   assert.ok(/live twin cannot be created/.test(said))
 })
 
-test('★ 조치를 구현하고 선언하지 않아도 말해 준다 — 같은 규율이다', () => {
+test('★ 구동을 구현하고 선언하지 않아도 말해 준다 — 같은 규율이다', () => {
   const before = warnings.length
   const a = adapter({ control: async () => ({ ok: true }) })
   registerAdapterType(a)
   assert.ok(warnings.slice(before).join('\n').includes('control'))
 })
 
-test('둘 다 어긋나면 둘 다 말한다 — 하나만 말하면 고친 뒤 또 막힌다', () => {
+test('★ 조치를 구현하고 선언하지 않아도 말해 준다 — 그 이름이 없어서 오늘 하루가 갔다', () => {
+  /*
+   * 이 자리에 `actuate` 가 없었다. 능력 축이 `live`·`control` 둘뿐이라 커넥터는 조치를 **선언할
+   * 방법이 없었고**, 등록 검사도 그것을 물을 수 없었다. MES 커넥터는 그 사이에 `actuate` 를 다
+   * 만들어 두었는데, 넘기는 자리는 「구현이 없습니다」로 답했다.
+   *
+   * 그 문장이 그럴듯해서 설계 문서와 다른 레인에까지 사실로 옮겨졌다. 오류가 아니라 **정직해 보이는
+   * 거절**이 원인이었다.
+   */
   const before = warnings.length
-  const a = adapter({ openLiveFeed: () => () => {}, control: async () => ({ ok: true }) })
+  const a = adapter({ actuate: async () => ({ ok: true }) })
   registerAdapterType(a)
+
   const said = warnings.slice(before).join('\n')
-  assert.ok(said.includes('live') && said.includes('control'))
+  assert.ok(said.includes('actuate'), '무엇이 빠졌는지 말한다')
+  assert.ok(said.includes(a.type), '어느 커넥터인지 말한다')
+})
+
+test('여럿이 어긋나면 다 말한다 — 하나만 말하면 고친 뒤 또 막힌다', () => {
+  const before = warnings.length
+  const a = adapter({
+    openLiveFeed: () => () => {},
+    control: async () => ({ ok: true }),
+    actuate: async () => ({ ok: true })
+  })
+  registerAdapterType(a)
+
+  const said = warnings.slice(before).join('\n')
+  for (const name of ['live', 'control', 'actuate']) {
+    assert.ok(said.includes(name), `${name} 를 말하지 않았다`)
+  }
+})
+
+test('★ 능력 이름이 늘면 검사도 함께 는다 — 표 하나에서 돈다', () => {
+  /*
+   * 예전에는 검사할 능력 셋이 코드 안에 손으로 적혀 있었다(`['live','control']`). 새 능력을 넣을 때
+   * 판정에는 넣고 검사에는 잊으면, **구현했는데 선언 안 한 것을 아무도 말해 주지 않는다** — 오늘 그
+   * 상태였다.
+   *
+   * 지금은 능력↔메서드 표 하나에서 돈다. 이 시험은 그 표가 실제로 셋을 다 덮는지 본다 — 넷째 능력을
+   * 넣고 표에 안 적으면 여기서 걸린다.
+   */
+  const cases: [string, Record<string, unknown>][] = [
+    ['live', { openLiveFeed: () => () => {} }],
+    ['control', { control: async () => ({ ok: true }) }],
+    ['actuate', { actuate: async () => ({ ok: true }) }]
+  ]
+
+  for (const [name, impl] of cases) {
+    const before = warnings.length
+    registerAdapterType(adapter(impl))
+    assert.ok(
+      warnings.slice(before).join('\n').includes(name),
+      `${name} 를 구현하고 선언하지 않았는데 아무 말도 하지 않았다 — 검사 표에 그 이름이 없다`
+    )
+  }
 })
 
 test('선언과 구현이 맞으면 아무 말도 하지 않는다 — 소음이 되면 아무도 읽지 않는다', () => {

package/test/declaration-reaches-model.test.ts

@@ -88,6 +88,9 @@ const VALUE: Record<string, unknown> = {
   gs1Id: 'urn:epc:id:sgln:0614141.00001.0',
   /* 설비의 정체성 — **GS1 키가 아닌 것이 정상이다**(실측: 인버터 하드웨어 식별자). */
   identity: 'ES100000007d8d061d-1',
+  /* 설비 등급 소속 — 2026-09-04 에 이 칸이 접수면에 없어서 원본이 채운 등급 22대가 문턱에서
+     버려졌다(인티그레이션 레인 실측). 사람·자산은 받는데 설비만 없었다. */
+  equipmentClassIds: ['welding-robot'],
   homeLocationId: 'cut-station',
   mtbfMs: 600000,
   mttrMs: 60000,
@@ -178,3 +181,43 @@ for (const c of CASES) {
     )
   })
 }
+
+/*
+ * ── 공간의 시각 기준도 모델까지 간다 (2026-09-07) ────────────────────────────
+ *
+ * 위 검사는 **자원**의 필드만 본다. `space` 는 안 보고 있었고, 그래서 실제로 하나가 새고 있었다 —
+ * `space.timezone` 이 오프셋으로만 풀려 모델에 실리고 **이름은 버려졌다.**
+ *
+ * 이름이 없으면 소비처가 순간마다 다시 풀 수 없다. 지난 구간을 교대별로 접을 때 그 구간 안의
+ * 일광절약시간 전환이 사실을 한 시간 밀어 **다른 교대로** 세게 하고, 오류는 나지 않는다.
+ * `America/Tijuana`(PST −480 / PDT −480 아닌 −420)가 이미 자료에 있다.
+ *
+ * 그리고 이 새는 자리를 잡은 것은 타입 검사도, 위 하네스도 아니라 **다른 레인의 물음**이었다
+ * ("자료를 채운 뒤 이미 세워진 모델이 따라가나"). 그래서 여기 검사로 남긴다.
+ */
+const withSpace = (space: Record<string, unknown>) => masterToTwin({ ...master(), space: { ...master().space, ...space } })
+
+test('공간의 시간대 이름이 모델까지 간다 — 오프셋만 실으면 계절이 바뀔 때 틀린다', () => {
+  const { model } = withSpace({ timezone: 'America/Tijuana' })
+
+  assert.equal((model as any).timezone, 'America/Tijuana', '이름이 모델에 없다 — 소비처가 순간마다 풀 수 없다')
+  assert.equal(typeof (model as any).utcOffsetMinutes, 'number', '오프셋도 함께 실려야 한다 — 이름을 안 보는 소비처가 그 값으로 돈다')
+})
+
+test('시간대를 선언하지 않으면 두 칸 다 만들지 않는다 — 0 은 「UTC 라고 선언했다」는 주장이다', () => {
+  const { model } = withSpace({})
+
+  assert.equal((model as any).timezone, undefined)
+  assert.equal((model as any).utcOffsetMinutes, undefined)
+})
+
+test('풀리지 않는 이름은 싣지 않고 경고로 말한다 — 실어 두면 소비처가 믿고 매번 실패한다', () => {
+  const { model, warnings } = withSpace({ timezone: 'Mars/Olympus_Mons' })
+
+  assert.equal((model as any).timezone, undefined)
+  assert.equal((model as any).utcOffsetMinutes, undefined)
+  assert.ok(
+    (warnings ?? []).some((w: any) => JSON.stringify(w).includes('Mars/Olympus_Mons')),
+    '모르는 시간대를 조용히 버리지 않는다'
+  )
+})

package/test/dedupe-transformation.test.ts

@@ -0,0 +1,112 @@
+/*
+ * 변환·담김의 정체가 **무엇이 무엇으로 되었나**로 갈리나.
+ *
+ * ── 왜 필요한가 (2026-09-07) ────────────────────────────────────────────────
+ * 이 자리가 없어서 **사실 하나가 없어졌습니다.** 거절이 아니라 되풀이로 세어져서 경고도 없었습니다.
+ *
+ * ```
+ * plant outbox seq 37   in LOT-CT-SIDE-001 24개  →  out LOT-CT-MAIN-003 12개
+ * plant outbox seq 42   in LOT-CT-SIDE-001 18개  →  out LOT-CT-MAIN-004  9개
+ *                       transformationID · bizStep · 초까지 전부 같다
+ * 저널에 남은 것        LOT-CT-MAIN-003 하나
+ * ```
+ *
+ * `LOT-CT-MAIN-004` 를 어느 패널로 만들었는지 트윈이 답하지 못했습니다. 인티그레이션 레인이
+ * 원본과 저널의 건수를 맞춰 보다 찾았습니다 — 4건이 나갔고 3건이 앉았습니다.
+ *
+ * 아래 값은 그 두 봉투에서 온 것입니다. 지어낸 모양이 아닙니다.
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import { factIdentity } from '../server/engine/ingest-dedupe.js'
+
+const AT = '2026-09-05T05:00:00.000Z'
+
+const transformation = (inQty: number, outClass: string, outQty: number) => ({
+  eventId: `evt-${outClass}-${outQty}`,
+  eventType: 'epcis.TransformationEvent',
+  eventTime: AT,
+  data: {
+    type: 'TransformationEvent',
+    bizStep: 'urn:epcglobal:cbv:bizstep:commissioning',
+    transformationID: 'WO-20260831-001',
+    inputQuantityList: [{ epcClass: 'LOT-CT-SIDE-001', quantity: inQty }],
+    outputQuantityList: [{ epcClass: outClass, quantity: outQty }]
+  }
+})
+
+test('산출 로트가 다르면 다른 사실이다 — 이것이 실제로 없어진 자리다', () => {
+  const a = factIdentity(transformation(24, 'LOT-CT-MAIN-003', 12))
+  const b = factIdentity(transformation(18, 'LOT-CT-MAIN-004', 9))
+
+  assert.ok(a, '정체를 만들지 못하면 dedupe 밖이다')
+  assert.notEqual(a, b, '같은 오더·같은 공정·같은 초라도 산출이 다르면 다른 변환이다')
+})
+
+test('똑같은 봉투가 두 번 오면 한 사실이다 — 갈라 놓기만 하면 되풀이를 못 막는다', () => {
+  assert.equal(
+    factIdentity(transformation(24, 'LOT-CT-MAIN-003', 12)),
+    factIdentity(transformation(24, 'LOT-CT-MAIN-003', 12))
+  )
+})
+
+test('산출 이름이 같고 수량만 다르면 다른 사실이다 — 분할이 그 모양이다', () => {
+  const a = factIdentity(transformation(24, 'LOT-CT-MAIN-003', 12))
+  const b = factIdentity(transformation(24, 'LOT-CT-MAIN-003', 6))
+
+  assert.notEqual(a, b)
+})
+
+test('입력 수량만 다르면 다른 사실이다 — 산출이 같아도 소비가 다르다', () => {
+  const a = factIdentity(transformation(24, 'LOT-CT-MAIN-003', 12))
+  const b = factIdentity(transformation(18, 'LOT-CT-MAIN-003', 12))
+
+  assert.notEqual(a, b)
+})
+
+test('오더가 다르면 다른 사실이다 — 같은 공정을 두 오더로 같은 초에 돌릴 수 있다', () => {
+  const withTx = (tx: string) => {
+    const e = transformation(24, 'LOT-CT-MAIN-003', 12) as any
+    e.data.bizTransactionList = [{ type: 'urn:epcglobal:cbv:btt:prodorder', bizTransaction: tx }]
+    return factIdentity(e)
+  }
+
+  assert.notEqual(withTx('urn:x:bt:WO-A'), withTx('urn:x:bt:WO-B'))
+})
+
+test('담김의 자식이 다르면 다른 사실이다 — 한 종류만 고치면 나머지에 같은 결함이 남는다', () => {
+  const aggregation = (child: string) => ({
+    eventId: `agg-${child}`,
+    eventType: 'epcis.AggregationEvent',
+    eventTime: AT,
+    data: {
+      type: 'AggregationEvent',
+      action: 'ADD',
+      bizStep: 'urn:epcglobal:cbv:bizstep:packing',
+      parentID: 'urn:epc:id:sscc:0614141.1234567890',
+      childQuantityList: [{ epcClass: child, quantity: 10 }]
+    }
+  })
+
+  assert.notEqual(factIdentity(aggregation('LOT-A')), factIdentity(aggregation('LOT-B')))
+})
+
+test('수량 목록 전체를 본다 — 첫 원소만 보면 뒤가 다른 둘이 뭉친다', () => {
+  const twoLines = (second: string) => ({
+    eventId: `evt-${second}`,
+    eventType: 'epcis.TransformationEvent',
+    eventTime: AT,
+    data: {
+      type: 'TransformationEvent',
+      bizStep: 'urn:epcglobal:cbv:bizstep:commissioning',
+      transformationID: 'WO-20260831-001',
+      outputQuantityList: [
+        { epcClass: 'LOT-SAME', quantity: 1 },
+        { epcClass: second, quantity: 1 }
+      ]
+    }
+  })
+
+  assert.notEqual(factIdentity(twoLines('LOT-X')), factIdentity(twoLines('LOT-Y')))
+})

package/test/entity-delta.test.ts

@@ -47,7 +47,7 @@ test('무버: OEE 는 정수 퍼센트로 정형화하고 원시 누적은 빼
         id: 'cutter-1',
         kind: 'cutter',
         status: 'down',
-        oee: { overall: 0.8234, availability: 0.9, performance: 0.95, quality: 0.96, goodCount: 12, scrapCount: 3, idleMs: 99999 }
+        oee: { overall: 0.8234, availability: 0.9, performance: 0.95, quality: 0.96, goodCount: 12, nonconformingCount: 3, idleMs: 99999 }
       }
     ]
   }, 't1')

package/test/event-subjects.test.ts

@@ -91,7 +91,8 @@ test('★ 같은 대상을 두 번 적지 않는다 — 출발지와 도착지
 })
 
 test('종류 목록이 닫혀 있다 — 열어 두면 넣는 쪽마다 다른 이름을 쓴다', () => {
-  assert.deepEqual([...SUBJECT_KINDS], ['item', 'lot', 'order', 'location', 'equipment', 'task'])
+  /* `transaction` 은 2026-09-05 에 늘었다 — 거래가 오더 칸에 섞여 들어오던 것을 갈랐다. */
+  assert.deepEqual([...SUBJECT_KINDS], ['item', 'lot', 'order', 'location', 'equipment', 'task', 'transaction'])
 })
 
 test('너무 긴 식별자는 적지 않는다 — 자르면 그 줄이 다른 대상을 가리킨다', () => {

package/test/external-resolver.test.ts

@@ -0,0 +1,171 @@
+/*
+ * ★ **밖을 가리키는 관계를 푸는 자리** — 선언은 있고 코드가 0곳이던 이음새.
+ *
+ * ── 무엇이 있었나 (2026-09-05 실측) ────────────────────────────────────────
+ * 계약이 `target: { kind: 'external', entity: … }` 를 선언하고 주석에 「해소는 호스트가 한다」고
+ * 적어 두었다. 그런데 `headless-twin/server` 어디에도 그것을 다루는 코드가 없었다(0곳).
+ *
+ * `space.area` 가 도는 것처럼 보인 이유는 이음새가 있어서가 아니라 **호스트에서 그것이 평범한 FK
+ * 라서**다 — 선언이 길을 낸 것이 아니다.
+ *
+ * ── 왜 지금 채웠나 ─────────────────────────────────────────────────────────
+ * 아침에는 「아무도 안 막혔으니 급하지 않다」로 적었고 **그 판단이 규모를 작게 잡은 것**이었다.
+ *
+ * 360 의 소비처는 무한히 늘어난다(사용자 방향). 그러면 각 제품의 자기 저장소가 관계의 원천이 된다.
+ * 그때 선언은 「밖을 가리킨다」고 말하는데 푸는 길이 없으면 **제품마다 자기 길을 낸다** — 그것이
+ * 정확히 「무한히 갈린다」다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  clearExternalResolvers,
+  externalIncoming,
+  externalResolverEntities,
+  registerExternalResolver,
+  resolveExternal
+} from '../server/service/twin-model/external-resolver.js'
+
+const AREA = 'space.area'
+
+/* ── 못 풀면 못 푼다고 말한다 ────────────────────────────────────────────── */
+
+test('★ 꽂힌 것이 없으면 「해소기가 없다」고 말한다 — 「없다」가 아니다', async () => {
+  /*
+   * 링크를 지우면 화면은 「그런 관계가 없다」로 읽는다. 실제로는 「아무도 답할 수 없다」다.
+   * 사람이 할 일이 다르다 — 앞은 자료를 채울 일이고 뒤는 해소기를 꽂을 일이다.
+   */
+  clearExternalResolvers()
+  const got = await resolveExternal(AREA, 'd1', ['LINE-CAM'])
+
+  assert.equal(got.unresolved, 'no-resolver')
+  assert.equal(got.refs, undefined)
+})
+
+test('★ 해소기가 터져도 360 을 죽이지 않는다 — 알리고 못 풀었다고 한다', async () => {
+  clearExternalResolvers()
+  const said: string[] = []
+  registerExternalResolver({ entity: AREA, resolve: async () => { throw new Error('DB down') } })
+
+  const got = await resolveExternal(AREA, 'd1', ['X'], m => said.push(m))
+
+  assert.equal(got.unresolved, 'failed')
+  assert.ok(said.some(m => m.includes('DB down')), '사유를 삼켰다')
+})
+
+/* ── 풀면 무엇인지 말한다 ────────────────────────────────────────────────── */
+
+test('★ 이름과 갈 곳을 낸다 — 막다른 링크를 만들지 않으려고', async () => {
+  clearExternalResolvers()
+  registerExternalResolver({
+    entity: AREA,
+    resolve: async (_d, ids) => ids.map(id => ({ id, name: `라인 ${id}`, href: `/areas/${id}` }))
+  })
+
+  const got = await resolveExternal(AREA, 'd1', ['LINE-CAM'])
+  assert.equal(got.refs?.[0].name, '라인 LINE-CAM')
+  assert.equal(got.refs?.[0].href, '/areas/LINE-CAM')
+})
+
+test('★ 없는 id 는 없다고 말한다 — 답에서 빼지 않는다', async () => {
+  /* 빼면 화면은 그 참조가 원래 없었던 것으로 읽는다. 실제로는 가리키는데 대상이 없는 것이다. */
+  clearExternalResolvers()
+  registerExternalResolver({ entity: AREA, resolve: async (_d, ids) => ids.map(id => ({ id, missing: true })) })
+
+  const got = await resolveExternal(AREA, 'd1', ['사라진구역'])
+  assert.equal(got.refs?.length, 1)
+  assert.equal(got.refs?.[0].missing, true)
+})
+
+/* ── 들어오는 쪽 ─────────────────────────────────────────────────────────── */
+
+test('★ 제품이 자기 저장소의 관계를 싣는다 — 커널은 그 표를 모른다', async () => {
+  clearExternalResolvers()
+  registerExternalResolver({
+    entity: 'mes.records',
+    incoming: async () => [
+      { via: 'mes.rel.report', from: 'productionReports', tense: 'past', ids: ['PR-1', 'PR-2'], total: 2 },
+      { via: 'mes.rel.maintenance', from: 'maintenancePlans', tense: 'future', ids: ['MP-1'], total: 1 }
+    ]
+  })
+
+  const got = await externalIncoming('d1', 'mes-miratek', 'equipment', 'EQ-CT-MWELD-01')
+
+  assert.equal(got.length, 2)
+  assert.deepEqual(got.map(g => g.tense).sort(), ['future', 'past'], '시간축이 안 실렸다')
+})
+
+test('★ 시간축이 실린다 — 「걸린 것이 열」이 두 뜻이 되는 자리', async () => {
+  /*
+   * 지난 일 아홉 · 앞으로 올 일 하나와 그 반대는 「이 설비를 세워도 되나」의 답이 정반대다.
+   * 묶음이 스스로 말해야 화면이 가를 수 있다.
+   */
+  clearExternalResolvers()
+  registerExternalResolver({
+    entity: 'mes.records',
+    incoming: async () => [{ via: 'mes.rel.report', from: 'x', tense: 'past', ids: ['a'], total: 9 }]
+  })
+
+  const got = await externalIncoming('d1', 'i', 'equipment', 'E-1')
+  assert.equal(got[0].tense, 'past')
+  assert.equal(got[0].total, 9, '전체 수를 안 말한다 — 잘린 목록만으로는 규모를 모른다')
+})
+
+test('빈 묶음은 싣지 않는다 — 그 제품이 이 축을 안 보는 것이고 할 말이 없다', async () => {
+  clearExternalResolvers()
+  registerExternalResolver({
+    entity: 'mes.records',
+    incoming: async () => [{ via: 'x', from: 'y', ids: [], total: 0 }]
+  })
+  assert.deepEqual(await externalIncoming('d1', 'i', 'equipment', 'E-1'), [])
+})
+
+test('★ 한 제품이 터져도 나머지는 실린다', async () => {
+  clearExternalResolvers()
+  const said: string[] = []
+  registerExternalResolver({ entity: 'broken', incoming: async () => { throw new Error('boom') } })
+  registerExternalResolver({
+    entity: 'ok',
+    incoming: async () => [{ via: 'v', from: 'f', ids: ['a'], total: 1 }]
+  })
+
+  const got = await externalIncoming('d1', 'i', 'equipment', 'E-1', m => said.push(m))
+  assert.equal(got.length, 1, '하나가 터져서 나머지도 안 실렸다')
+  assert.ok(said.some(m => m.includes('boom')))
+})
+
+/* ── 꽂는 규율 ───────────────────────────────────────────────────────────── */
+
+test('★ 같은 대상을 두 제품이 답하려 하면 알린다 — 조용히 덮지 않는다', async () => {
+  clearExternalResolvers()
+  const said: string[] = []
+  registerExternalResolver({ entity: AREA, resolve: async () => [] })
+  registerExternalResolver({ entity: AREA, resolve: async () => [] }, m => said.push(m))
+
+  assert.ok(said.some(m => m.includes(AREA)), '덮어쓴 것을 안 알렸다')
+})
+
+test('entity 없는 해소기는 안 꽂는다 — 아무 관계에도 안 붙는다', async () => {
+  clearExternalResolvers()
+  const said: string[] = []
+  registerExternalResolver({ entity: '  ' } as any, m => said.push(m))
+
+  assert.deepEqual(externalResolverEntities(), [])
+  assert.ok(said.length, '조용히 넘겼다')
+})
+
+test('★ 무엇을 풀 수 있나를 밖에서 잴 수 있다 — 「모른다」와 「없다」를 가르려고', async () => {
+  clearExternalResolvers()
+  registerExternalResolver({ entity: 'b', resolve: async () => [] })
+  registerExternalResolver({ entity: 'a', resolve: async () => [] })
+
+  assert.deepEqual(externalResolverEntities(), ['a', 'b'])
+})
+
+test('★ 이 검사가 실제로 무언가를 잰다 — 견준 것이 0이면 빨강', async () => {
+  clearExternalResolvers()
+  assert.deepEqual(externalResolverEntities(), [], '지우기가 안 듣는다')
+  registerExternalResolver({ entity: AREA, resolve: async (_d, ids) => ids.map(id => ({ id })) })
+  const got = await resolveExternal(AREA, 'd', ['X'])
+  assert.equal(got.refs?.length, 1, '꽂았는데 안 불린다')
+})

package/test/fill-dedupe.test.ts

@@ -0,0 +1,59 @@
+/*
+ * backfill 이 이미 있는 사실을 다시 앉히지 않게 하는 부분.
+ *
+ * ── 무엇이 있었나 (2026-09-06 측정) ─────────────────────────────────────────
+ * 중복 판정 기억은 프로세스 안에만 있다. 재기동하면 비워지고, 그 뒤 backfill 을 돌리면 이미 저널에
+ * 있는 사실도 「처음 본 것」이 된다.
+ *
+ * ```
+ * mes-line-a 를 재기동 뒤 backfill
+ *   저널 44 → 83건 · 서로 다른 것 39가지 · 중복 44가지
+ *   같은 프로세스에서 다시 돌리면 applied 0    (기억이 살아 있어서)
+ * ```
+ *
+ * 저널 조회는 DB 를 물어야 해서 여기서 다루지 않는다. 확인하는 것은 **어느 구간을 읽을지 정하는
+ * 판정**이다 — 그것이 틀리면 조회가 엉뚱한 곳을 보고 기억이 안 찬다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { spanOf } from '../server/service/reference/fill-span.js'
+
+const at = (s: string) => ({ subjectId: 'L', decision: 'scrap', at: s })
+
+test('★ 레코드가 덮는 구간을 정한다', () => {
+  const span = spanOf([at('2026-09-01T00:00:00.000Z'), at('2026-09-03T12:00:00.000Z'), at('2026-09-02T00:00:00.000Z')])
+  assert.ok(span)
+  assert.equal(span!.from.toISOString(), '2026-08-31T23:59:59.000Z')
+  assert.equal(span!.to.toISOString(), '2026-09-03T12:00:01.000Z')
+})
+
+test('★ 양쪽을 1초씩 넓힌다 — 좁게 읽으면 경계의 사실이 다시 앉는다', () => {
+  /*
+   * 저장된 시각은 밀리초까지 있고 경계에서 같은 값이 갈릴 수 있다. 넓게 읽는 것은 기억이 조금 더
+   * 차는 것뿐이라 손해가 없다.
+   */
+  const one = '2026-09-01T00:00:00.000Z'
+  const span = spanOf([at(one)])!
+  assert.equal(span.to.getTime() - span.from.getTime(), 2000)
+})
+
+test('★ 하나도 시각을 안 말하면 구간이 없다 — 저널 전체를 읽지 않는다', () => {
+  /*
+   * 구간을 못 정하면 채우지 않는다. 저널 전체를 읽는 쪽으로 넓히면 2백만 줄을 훑게 되고, 그것이
+   * 필요한 상황이면 조회가 아니라 정체 색인으로 풀어야 한다.
+   */
+  assert.equal(spanOf([{ subjectId: 'L', decision: 'scrap' }]), undefined)
+  assert.equal(spanOf([]), undefined)
+})
+
+test('시각을 말하는 것과 안 말하는 것이 섞이면 말하는 것으로 정한다', () => {
+  const span = spanOf([{ subjectId: 'A' }, at('2026-09-01T00:00:00.000Z'), { subjectId: 'B' }])
+  assert.ok(span, '한 줄이라도 말하면 구간이 있다')
+})
+
+test('★ 이 테스트가 실제로 무언가를 잰다 — 견준 것이 0이면 빨강', () => {
+  const narrow = spanOf([at('2026-09-01T00:00:00.000Z')])!
+  const wide = spanOf([at('2026-09-01T00:00:00.000Z'), at('2026-09-10T00:00:00.000Z')])!
+  assert.ok(wide.to.getTime() > narrow.to.getTime(), '구간이 레코드를 안 따라간다')
+})

package/test/fill-loop.test.ts

@@ -0,0 +1,35 @@
+/*
+ * 빠진 구간을 **언제** 다시 받나 — 세 자리의 규율.
+ *
+ * ```
+ * 1  재기동 직후 한 번    우리가 내려가 있는 동안 그쪽이 보낸 것
+ * 2  구멍을 본 그 자리     번호가 비었다는 것을 아는 가장 이른 순간
+ * 3  10분 그물            위 둘이 다 놓치는 경우
+ * ```
+ *
+ * 여기서 확인하는 것은 **두 번 부르지 않는 규율**이다. 밀어 받는 쪽이 구멍 뒤의 봉투를 계속 보내면
+ * 그때마다 구멍 판정이 나고, 막지 않으면 봉투마다 backfill 이 돈다.
+ *
+ * 실제 조회는 DB 와 어댑터를 물어야 해서 여기서 다루지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { FILL_DEBOUNCE_MS, FILL_PERIOD_MS } from '../server/service/reference/fill-cadence.js'
+
+test('★ 그물은 10분이다 — 30초가 아니다', () => {
+  /*
+   * 인티그레이션 레인이 측정으로 준 권고다. backfill 은 원본에 조회를 걸고 저널을 읽는다.
+   * 30초마다 돌면 얻는 것 없이 두 쪽을 계속 친다 — 놓친 구간은 10분 뒤에 받아도 사실이 달라지지 않는다.
+   *
+   * 규칙 주기(30초)에 얹지 않은 이유이기도 하다. 얹으면 간격이 그쪽에 묶이고, 나중에 규칙 주기를
+   * 바꾸면 이쪽이 소리 없이 따라간다.
+   */
+  assert.equal(FILL_PERIOD_MS, 10 * 60_000)
+  assert.notEqual(FILL_PERIOD_MS, 30_000, '규칙 주기와 같아졌다 — 그러면 하나를 바꿀 때 둘이 움직인다')
+})
+
+test('★ 같은 단위를 1분 안에 두 번 안 받는다 — 봉투마다 돌면 안 된다', () => {
+  assert.equal(FILL_DEBOUNCE_MS, 60_000)
+  assert.ok(FILL_DEBOUNCE_MS < FILL_PERIOD_MS, '막는 간격이 그물보다 길면 그물이 헛돈다')
+})