@things-factory/headless-twin 10.0.18 → 10.1.0

package/test/live-feed-lease.test.ts

@@ -0,0 +1,63 @@
+/*
+ * The name a live feed takes its lease under.
+ *
+ * This is worth a test because the failure it prevents is silent: two feeds
+ * sharing one name means one of them stops, and it stops looking like
+ * "someone else holds it" — the ordinary case on every instance but one, so
+ * nothing gets logged and nothing looks wrong.
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import { liveFeedLeaseName } from '../server/service/reference/live-feed-lease.js'
+
+test('the domain is part of the name, so two tenants do not block each other', () => {
+  /*
+   * This is the whole reason the reference layer composes the name instead of
+   * the adapter: an adapter is handed cfg and site, and neither carries a
+   * domain, so a name built there would collide across tenants.
+   */
+  const a = liveFeedLeaseName('domain-a', 'mes-line-a', 'mes')
+  const b = liveFeedLeaseName('domain-b', 'mes-line-a', 'mes')
+
+  assert.notEqual(a, b)
+  assert.ok(a.includes('domain-a'))
+})
+
+test('the instance is part of the name, so two twins on one source do not block each other', () => {
+  const a = liveFeedLeaseName('d', 'mes-line-a', 'mes')
+  const b = liveFeedLeaseName('d', 'mes-miratek', 'mes')
+
+  assert.notEqual(a, b)
+})
+
+test('the same feed always gets the same name, so a second instance sees it as taken', () => {
+  assert.equal(liveFeedLeaseName('d', 'i', 's'), liveFeedLeaseName('d', 'i', 's'))
+})
+
+test('the name says it is a live feed, so a lease table read tells you the kind of task', () => {
+  assert.ok(liveFeedLeaseName('d', 'i', 's').startsWith('twin-live::'))
+})
+
+test('a missing source still names the feed — an instance has one feed', () => {
+  const named = liveFeedLeaseName('d', 'i')
+
+  assert.equal(named, 'twin-live::d::i')
+  assert.notEqual(named, liveFeedLeaseName('d', 'other'))
+})
+
+test('a blank source is the same as none rather than an empty segment', () => {
+  assert.equal(liveFeedLeaseName('d', 'i', '   '), liveFeedLeaseName('d', 'i'))
+})
+
+test('a missing domain or instance is refused, not filled in', () => {
+  /*
+   * Composing a name from a blank would put two feeds on one row. Throwing
+   * here surfaces it at startup; filling it in would surface it as a channel
+   * that quietly stopped weeks later.
+   */
+  assert.throws(() => liveFeedLeaseName('', 'i', 's'), /domainId/)
+  assert.throws(() => liveFeedLeaseName('   ', 'i', 's'), /domainId/)
+  assert.throws(() => liveFeedLeaseName('d', '', 's'), /instanceId/)
+  assert.throws(() => liveFeedLeaseName('d', undefined as any, 's'), /instanceId/)
+})

package/test/live-mirror-parity.test.ts

@@ -213,7 +213,7 @@ test('★ OEE derive: 공유 공식 computeOee 가 공급된 카운터로 OEE
    */
   const planned = o.runMs + o.setupMs + o.downMs + o.delayMs
   const derived = computeOee(
-    { runMs: o.runMs, setupMs: o.setupMs, downMs: o.downMs, goodCount: o.goodCount, scrapCount: o.scrapCount, metricsSinceMs: 0 },
+    { runMs: o.runMs, setupMs: o.setupMs, downMs: o.downMs, goodCount: o.goodCount, nonconformingCount: o.nonconformingCount, metricsSinceMs: 0 },
     planned
   )
   /* 세 비율은 근거가 없으면 없다 — 양쪽 다 없는 것도 재생산이다(계약 0.5.0). */

package/test/oee-accumulator.test.ts

@@ -90,13 +90,13 @@ test('★ OEE 누적기: quality.output 델타 소비 → quality 정확 (good/s
   const ev = (ms: number, type: string, data: any): any => ({ eventId: 'x', eventType: type, eventTime: new Date(T0 + ms).toISOString(), tenantId: 't', data })
 
   acc.apply(ev(0, 'equipment.status', { moverId: 'w1', status: 'busy' }))
-  acc.apply(ev(1000, 'quality.output', { moverId: 'w1', good: false, goodCount: 0, scrapCount: 1 }))
-  acc.apply(ev(2000, 'quality.output', { moverId: 'w1', good: true, goodCount: 8, scrapCount: 2 })) // 누적값 최신화
+  acc.apply(ev(1000, 'quality.output', { moverId: 'w1', good: false, goodCount: 0, nonconformingCount: 1 }))
+  acc.apply(ev(2000, 'quality.output', { moverId: 'w1', good: true, goodCount: 8, nonconformingCount: 2 })) // 누적값 최신화
   acc.apply(ev(3000, 'equipment.status', { moverId: 'w1', status: 'idle' }))
 
   const c = acc.counters('w1', T0 + 4000)
   assert.equal(c.goodCount, 8, 'goodCount 추적(누적 최신)')
-  assert.equal(c.scrapCount, 2, 'scrapCount 추적')
+  assert.equal(c.nonconformingCount, 2, 'nonconformingCount 추적')
   const oee = acc.oee('w1', T0 + 4000)
   assert.ok(Math.abs(oee.quality - 0.8) < 1e-9, 'quality = good/(good+scrap) = 0.8 (텔레메트리 없이 이벤트로 도출)')
 })

package/test/oee-site-calendar.test.ts

@@ -0,0 +1,146 @@
+/*
+ * 현장의 조업 달력이 계획 조업 시간에 닿나.
+ *
+ * ── 왜 필요한가 (2026-09-07) ────────────────────────────────────────────────
+ * 계획 조업 시간(PBT)이 「재기 시작한 뒤 흐른 시간 전부」였다. 주말도 야간도 휴일도 계획 조업으로
+ * 세었다. [산술] 8시간 × 주5일이면 168시간 중 40시간이 조업이니 PBT 가 4.2배 크다.
+ *
+ * plant 레인이 같은 자리를 먼저 겪고 실측을 냈다 — 3교대를 물려받으면 `availability 0.4583`,
+ * 달력이 아예 없으면 수를 안 낸다. 트윈은 창 전체를 계획으로 쳐서 수를 냈다.
+ *
+ * ── 이 시험이 지키는 것은 「자리가 있고 부르는 곳이 있다」다 ─────────────────
+ * 오늘 이 저장소에서 그것을 여섯 번 놓쳤다. 값을 받을 칸을 만들고 아무도 채우지 않거나, 채우고
+ * 아무도 안 읽는 자리다. 그래서 여기서는 **누적기가 그 값을 실제로 쓰는지**를 본다 — 달력을 얹은
+ * 것과 안 얹은 것의 답이 달라야 한다.
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import { OeeAccumulator } from '../server/engine/oee-accumulator.js'
+
+const HOUR = 3_600_000
+const MON = Date.UTC(2026, 8, 7, 0, 0, 0)
+
+/** 08:00~16:00 만 조업 — 하루 열여섯 시간이 비근무다. */
+const EIGHT_HOURS = [{ id: 'day', fromTime: '08:00', toTime: '16:00' }] as any[]
+
+/** 여덟 시간 내내 돈 설비 한 대. */
+function ranAllShift(calendar?: any[]) {
+  const acc = new OeeAccumulator()
+  acc.setWorkCalendar(calendar ? { workCalendar: calendar } : undefined)
+  /*
+   * 봉투의 `data` 에 `moverId` 다 — `payload.data` 도 `equipmentId` 도 아니다. 처음 그렇게 써서
+   * 누적기가 아무것도 안 받았고, 시험 넷이 빨개져서 알았다. 읽어서 고쳤다(`oee-accumulator.ts:111`).
+   */
+  acc.apply({
+    eventType: 'equipment.status',
+    eventTime: new Date(MON + 8 * HOUR).toISOString(),
+    data: { moverId: 'EQ-1', status: 'busy' }
+  } as any)
+
+  return acc.counters('EQ-1', MON + 24 * HOUR)
+}
+
+test('달력을 얹으면 계획 정지가 나온다 — 계측 창 안의 비근무만', () => {
+  /*
+   * ⚠ 하루가 아니다. 계측 창은 **첫 이벤트부터**이므로 08:00~24:00 의 열여섯 시간이고, 그중 조업이
+   * 08:00~16:00 이니 비근무가 여덟 시간이다.
+   *
+   * 처음 이 값을 열여섯으로 적었다 — 「하루 중 열여섯 시간이 비근무」라는 달력의 성질을 계측 창에
+   * 그대로 옮긴 것이다. 재보고 고쳤다. 계획 정지는 **달력의 성질이 아니라 이 창에서 잰 값**이다.
+   */
+  const c = ranAllShift(EIGHT_HOURS) as any
+
+  assert.equal(c.holdMs, 8 * HOUR)
+  assert.equal(c.metricsSinceMs, MON + 8 * HOUR, '창이 첫 이벤트부터라는 것이 위 계산의 전제다')
+})
+
+test('달력이 없으면 그 칸을 만들지 않는다 — 0 은 「쉬는 시간이 없다」는 주장이다', () => {
+  const c = ranAllShift() as any
+
+  assert.equal('holdMs' in c, false)
+})
+
+test('얹은 것과 안 얹은 것의 답이 다르다 — 같으면 그 값이 안 쓰이는 것이다', () => {
+  /*
+   * 이 시험이 이 파일의 요점이다. 오늘 제가 낸 결함 중 하나가 「값을 넣어 줄 사람이 있는지 아무것도
+   * 검사하지 않은 시험」이었다 — 고쳐도 통과하고 안 고쳐도 통과했다.
+   */
+  const withCal = ranAllShift(EIGHT_HOURS) as any
+  const without = ranAllShift() as any
+
+  assert.notEqual(withCal.holdMs, without.holdMs)
+})
+
+test('실 생산 시간은 달력과 무관하다 — APT 는 잰 값이다', () => {
+  /*
+   * 달력은 PBT 를 정하고 APT 는 안 건드린다. 휴일에 돌린 열한 시간이 사라지던 것이 그 반대 방향의
+   * 결함이었고, 그것은 자르는 쪽이었다.
+   */
+  const withCal = ranAllShift(EIGHT_HOURS)
+  const without = ranAllShift()
+
+  assert.equal(withCal.runMs, without.runMs)
+  assert.equal(withCal.runMs, 16 * HOUR, '08:00 에 busy 로 들어가 24:00 까지면 열여섯 시간이다')
+})
+
+test('잰 구간의 시작은 그대로다 — 그 칸에 파생값을 얹지 않는다', () => {
+  /*
+   * 같은 효과를 `metricsSinceMs` 를 당겨서 낼 수도 있는데, 그 칸은 「언제부터 쟀나」라는 사실이다.
+   * plant 레인이 그 방식으로 하고 있었고 `holdMs` 로 옮겼다 — 수는 자릿수까지 같았다.
+   */
+  const c = ranAllShift(EIGHT_HOURS)
+
+  assert.equal(c.metricsSinceMs, MON + 8 * HOUR)
+})
+
+/*
+ * ── 설비의 달력이 현장의 것을 이긴다 ────────────────────────────────────────
+ * 이 자리가 실제 자료를 살렸다. rosarito 트윈들이 설비 41대에 3교대 × 평일 달력을 이미 갖고 있었는데,
+ * 처음 배선할 때 **현장 달력만 읽었다.** 현장에 달력을 선언한 공간이 하나도 없어서, 있는 자료를 두고
+ * 계획 조업 시간이 창 전체로 남아 있었다.
+ *
+ * 사용자가 「모든 공간에 달력을 세우라」고 한 것이 그 말을 듣고 나온 지시였고, 재보니 세울 것이 아니라
+ * **읽을 것이 있었다.**
+ */
+const ROUND_CLOCK = [{ id: 'always', fromTime: '00:00', toTime: '24:00' }] as any[]
+
+function withModel(model: any) {
+  const acc = new OeeAccumulator()
+  acc.setWorkCalendar(model)
+  acc.apply({
+    eventType: 'equipment.status',
+    eventTime: new Date(MON + 8 * HOUR).toISOString(),
+    data: { moverId: 'EQ-1', status: 'busy' }
+  } as any)
+
+  return acc.counters('EQ-1', MON + 24 * HOUR) as any
+}
+
+test('설비가 자기 달력을 선언하면 그것을 쓴다 — 24시간 도는 로가 현장 근무조에 안 잘린다', () => {
+  const c = withModel({ workCalendar: EIGHT_HOURS, equipment: [{ id: 'EQ-1', workCalendar: ROUND_CLOCK }] })
+
+  assert.equal(c.holdMs, 0, '자기 달력이 종일 가동이면 계획 정지가 없다')
+})
+
+test('설비가 선언하지 않으면 현장의 달력으로 떨어진다', () => {
+  const c = withModel({ workCalendar: EIGHT_HOURS, equipment: [{ id: 'EQ-OTHER', workCalendar: ROUND_CLOCK }] })
+
+  assert.equal(c.holdMs, 8 * HOUR, '이 설비의 것이 없으니 현장 것을 쓴다')
+})
+
+test('현장이 없고 설비만 있어도 답한다 — 지금 실제 자료가 그 모양이다', () => {
+  /*
+   * rosarito 가 이렇다: 공간에 달력이 없고 설비 41대에 3교대가 있다. 현장 달력만 읽으면 이 자료가
+   * 통째로 안 쓰인다.
+   */
+  const c = withModel({ equipment: [{ id: 'EQ-1', workCalendar: EIGHT_HOURS }] })
+
+  assert.equal(c.holdMs, 8 * HOUR)
+})
+
+test('둘 다 없으면 그 칸을 만들지 않는다', () => {
+  const c = withModel({ equipment: [{ id: 'EQ-1' }] })
+
+  assert.equal('holdMs' in c, false)
+})

package/test/order-and-transaction-split.test.ts

@@ -0,0 +1,107 @@
+/*
+ * ★ **오더 식별자와 거래 식별자는 다른 칸에 든다** — 한 칸에 두 낱말이 들어가던 자리.
+ *
+ * ── 실측 (2026-09-05) ──────────────────────────────────────────────────────
+ * 승격 칸 `order_id` 하나가 두 낱말을 담고 있었다.
+ *
+ *   order.status                order-1                          내부 오더 id
+ *   epcis.TransformationEvent   urn:epc:id:gdti:9521321.403.1    GS1 거래 식별자
+ *
+ * 한 오더의 이력이 **색인 안에서 두 쪽으로 갈라진다.** 어느 이름으로 물어도 절반만 나오고,
+ * 오류는 나지 않는다. 어휘가 섞인 행 10,004개.
+ *
+ * 그 갈라짐이 막은 것은 「이 개체를 어느 레시피로 만들었나」다 — 답은 오더 사건에 이미 있는데
+ * (`recipeKey`, 실측 328,021/328,021), 변환 사건에서 그 오더로 건너갈 색인이 없었다.
+ *
+ * ── 왜 이 검사인가 ────────────────────────────────────────────────────────
+ * 「합치면 편하다」는 힘이 계속 작용한다 — 값을 채우는 관점에서는 한 칸이 간단해 보이고, 실제로
+ * 그 이유로 합쳐져 있었다(옛 주석이 「오더를 스스로 말하는 사건은 그 말을 그대로 쓴다」고 적고
+ * 있었다). 그러니 갈라 둔 것을 **값으로** 못 박는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { bizTransactionOf, orderOf, twinEventKeys } from '../server/service/twin-event/twin-event-keys.js'
+import { SUBJECT_KINDS, subjectsOf } from '../server/service/twin-subject/event-subjects.js'
+
+const GDTI = 'urn:epc:id:gdti:9521321.403.1'
+
+/** 실측한 변환 사건의 모양 — GDTI 만 있고 오더 id 는 없다. */
+const transformation = {
+  eventType: 'epcis.TransformationEvent',
+  data: {
+    type: 'TransformationEvent',
+    inputEPCList: ['urn:epc:id:sgtin:9521321.011111.1'],
+    outputEPCList: ['urn:epc:id:sgtin:9521321.033333.1'],
+    bizTransactionList: [{ type: 'urn:epcglobal:cbv:btt:prodorder', bizTransaction: GDTI }]
+  }
+}
+
+/** 실측한 오더 사건의 모양 — 둘 다 든다. 이것이 다리다. */
+const orderStatus = {
+  eventType: 'order.status',
+  data: { orderId: 'order-1', status: 'created', recipeKey: 'trailer', bizTransaction: GDTI }
+}
+
+/* ── 갈라져 있나 ─────────────────────────────────────────────────────────── */
+
+test('★ 변환 사건의 GDTI 는 거래 칸에 든다 — 오더 칸에 앉지 않는다', () => {
+  assert.equal(bizTransactionOf(transformation), GDTI)
+  assert.equal(orderOf(transformation), undefined, 'GDTI 가 오더 식별자 자리에 앉았다')
+})
+
+test('★ 오더 사건은 두 칸을 다 든다 — 이것이 EPCIS 에서 오더로 건너가는 다리다', () => {
+  const keys = twinEventKeys(orderStatus)
+  assert.equal(keys.orderId, 'order-1')
+  assert.equal(keys.bizTransaction, GDTI)
+})
+
+test('★ 두 사건이 같은 거래 값으로 이어진다 — 문자열까지 같아야 색인이 잇는다', () => {
+  /*
+   * 이 검사가 이 변경의 목적이다. 값이 한 글자라도 다르면 색인 조회가 0을 내고, 그 0은
+   * 「그런 오더가 없다」와 구별되지 않는다.
+   */
+  assert.equal(twinEventKeys(transformation).bizTransaction, twinEventKeys(orderStatus).bizTransaction)
+})
+
+test('★ 오더 사건에서 레시피를 읽을 수 있다 — 짐작하지 않아도 되는 근거', () => {
+  /* 자재로 되짚어 첫 레시피를 고르던 자리가 이 값으로 대체된다. */
+  assert.equal((orderStatus.data as any).recipeKey, 'trailer')
+})
+
+/* ── 합쳐지지 않았나 ──────────────────────────────────────────────────────── */
+
+test('★ 오더 칸이 거래로 되돌아가지 않는다 — 옛 되돌림(fallback)이 살아나면 빨강', () => {
+  /*
+   * 옛 코드: `d.orderId ?? d.bizTransactionList?.[0]?.bizTransaction`.
+   * 그 한 줄이 돌아오면 아래가 GDTI 를 내고, 두 낱말이 다시 한 칸에 든다.
+   */
+  const onlyTx = { eventType: 'epcis.ObjectEvent', data: { bizTransactionList: [{ bizTransaction: GDTI }] } }
+  assert.equal(orderOf(onlyTx), undefined, '오더 칸이 거래 값으로 되돌아간다')
+  assert.equal(bizTransactionOf(onlyTx), GDTI)
+})
+
+test('★ 주체 표도 갈라 적는다 — 거래가 오더 이름으로 앉지 않는다', () => {
+  const subjects = subjectsOf(transformation)
+  const kinds = (id: string) => subjects.filter(s => s.id === id).map(s => s.kind)
+
+  assert.deepEqual(kinds(GDTI), ['transaction'], `GDTI 가 붙은 종류가 다르다: ${JSON.stringify(subjects)}`)
+  assert.ok(SUBJECT_KINDS.includes('transaction' as any), '거래 종류가 목록에 없다')
+})
+
+test('★ 오더 사건은 두 주체를 다 낸다', () => {
+  const subjects = subjectsOf(orderStatus)
+  const has = (kind: string, id: string) => subjects.some(s => s.kind === kind && s.id === id)
+
+  assert.ok(has('order', 'order-1'), `오더 주체가 없다: ${JSON.stringify(subjects)}`)
+  assert.ok(has('transaction', GDTI), `거래 주체가 없다: ${JSON.stringify(subjects)}`)
+})
+
+/* ── 검사가 실제로 무언가를 재나 ─────────────────────────────────────────── */
+
+test('★ 이 검사가 실제로 무언가를 잰다 — 견준 것이 0이면 빨강', () => {
+  const keys = twinEventKeys(orderStatus)
+  assert.ok(Object.values(keys).filter(v => v !== undefined).length >= 3, `승격 키를 ${JSON.stringify(keys)} 만 뽑았다`)
+  assert.ok(subjectsOf(orderStatus).length >= 2, '주체가 둘도 안 나왔다')
+  assert.ok(subjectsOf(transformation).length >= 1, '변환 사건에서 주체가 하나도 안 나왔다')
+})

package/test/reference-fill.test.ts

@@ -0,0 +1,235 @@
+/*
+ * **놓친 구간을 backfill 해 채운다** — 그 길이 없었다.
+ *
+ * ── 무엇이 있었나 (2026-08-31, 인티그레이션 레인 지적) ────────────────────
+ * 번호로 「빠졌다」를 알아채게 만들었는데, 알아챈 뒤 **그 사이를 채우는 길이 없었다.** 설계가 적어 둔
+ * 길이고 양쪽이 다 읽었는데 만들지 않았다.
+ *
+ * ── 되풀이해 요청하는 경로에서 무너지는 것 ─────────────────────────────────────
+ * 행복한 길은 짧다. 무너지는 것은 **끝나지 않는 것**이다.
+ *
+ *   빈 답에 물어본 번호를 그대로 돌려주는 원본  → 무한히 요청한다
+ *   구멍 뒤를 이어 받는다                      → 커서가 그 번호를 지나쳐 적히고 빠진 사실은 안 온다
+ *   상한에 닿았는데 조용히 끝낸다               → 사람은 다 받은 줄로 읽는다
+ *
+ * 셋 다 오류가 나지 않는다. 그래서 시험이 셋을 만든다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { fillSince } from '../server/service/reference/reference-fill.js'
+import { pushCursorKey, seqOf } from '../server/service/reference/hook-contract.js'
+import type { InboundBatch } from '../server/service/reference/reference-adapter.js'
+
+const CFG = { baseUrl: 'x' }
+const SITE = { siteId: 's-1' }
+const SCOPE = 'EVENTS'
+const KEY = pushCursorKey('twin-a', SCOPE)
+
+/** 번호가 붙은 봉투 한 쪽. */
+const page = (seqs: number[], scope: string = SCOPE): InboundBatch => ({
+  scope,
+  items: seqs.map(seq => ({ seq, record: { moverId: `eq-${seq}`, kind: 'press', status: 'idle' } }))
+})
+
+/** 저장본 하나 — 프로세스가 아니라 여기 산다. */
+function harness(initial?: unknown) {
+  const state = { cursor: initial as unknown, saves: 0, ingested: [] as unknown[][] }
+  return {
+    state,
+    saveCursor: async (c: Record<string, unknown>) => {
+      state.saves++
+      state.cursor = JSON.parse(JSON.stringify(c))
+    },
+    ingest: (records: unknown[]) => {
+      state.ingested.push(records)
+      return { applied: records.length, duplicates: 0, rejected: [] }
+    }
+  }
+}
+
+const run = (h: ReturnType<typeof harness>, fetch: any, maxPages?: number) =>
+  fillSince({
+    cfg: CFG,
+    site: SITE,
+    scope: SCOPE,
+    cursorKey: KEY,
+    cursor: h.state.cursor,
+    fetch,
+    ingest: h.ingest,
+    saveCursor: h.saveCursor,
+    ...(maxPages ? { maxPages } : {})
+  })
+
+/* ── 채운다 ───────────────────────────────────────────────────────────────── */
+
+test('★ 커서 다음부터 요청하고 받은 데까지 커서를 올린다', async () => {
+  const h = harness({ streams: { [KEY]: { seq: 4 } } })
+  const asked: number[] = []
+  const out = await run(h, async (_c: any, _s: any, _sc: string, since: number) => {
+    asked.push(since)
+    return since === 4 ? page([5, 6]) : page([])
+  })
+
+  assert.deepEqual(asked, [4, 6], '받은 데부터 다시 요청한다')
+  assert.equal(out.applied, 2)
+  assert.equal(out.stopped, 'done')
+  assert.equal(seqOf(h.state.cursor, KEY), 6)
+})
+
+test('★ 커서가 없으면 0부터 요청한다. 처음 채우는 것이다', async () => {
+  const h = harness()
+  const asked: number[] = []
+  await run(h, async (_c: any, _s: any, _sc: string, since: number) => {
+    asked.push(since)
+    return since === 0 ? page([1, 2, 3]) : page([])
+  })
+  assert.equal(asked[0], 0)
+  assert.equal(seqOf(h.state.cursor, KEY), 3)
+})
+
+test('여러 쪽을 이어 받는다', async () => {
+  const h = harness()
+  const out = await run(h, async (_c: any, _s: any, _sc: string, since: number) => {
+    if (since === 0) return page([1, 2])
+    if (since === 2) return page([3, 4])
+    return page([])
+  })
+  assert.equal(out.applied, 4)
+  assert.equal(out.pages >= 2, true)
+  assert.equal(seqOf(h.state.cursor, KEY), 4)
+})
+
+/* ── 끝나지 않는 것을 막는다 ──────────────────────────────────────────────── */
+
+test('★ 번호가 나아가지 않으면 멈춘다 — 같은 것을 다시 주는 원본에 무한히 요청하지 않는다', async () => {
+  /*
+   * 아웃박스 계약이 「빈 묶음에는 물어본 번호를 그대로 돌려준다」이므로, 나아감을 보지 않고 요청하면
+   * 영원히 돈다. 실제로 그 계약을 쓰는 상대가 있다.
+   */
+  const h = harness({ streams: { [KEY]: { seq: 4 } } })
+  let calls = 0
+  const out = await run(h, async () => {
+    calls++
+    /* 이미 받은 번호만 돌려준다 — 커서가 나아가지 않는다. */
+    return page([3, 4])
+  })
+
+  assert.equal(out.stopped, 'no-progress')
+  assert.ok(calls <= 2, `무한히 요청했다 — ${calls}번`)
+  assert.match(String(out.detail), /나아가지 않았다/)
+})
+
+test('★ 빈 답은 끝이고 오류가 아니다', async () => {
+  const h = harness({ streams: { [KEY]: { seq: 9 } } })
+  const out = await run(h, async () => page([]))
+  assert.equal(out.stopped, 'done')
+  assert.equal(out.applied, 0)
+  assert.equal(out.detail, undefined)
+})
+
+/* ── 구멍 ─────────────────────────────────────────────────────────────────── */
+
+test('★ 구멍이 있으면 그 앞까지만 넣고 멈춘다 — 이어 받으면 빠진 사실이 다시 오지 않는다', async () => {
+  const h = harness({ streams: { [KEY]: { seq: 4 } } })
+  const out = await run(h, async (_c: any, _s: any, _sc: string, since: number) =>
+    since === 4 ? page([5, 6, 9, 10]) : page([])
+  )
+
+  assert.equal(out.stopped, 'gap')
+  assert.equal(out.applied, 2, '5·6 만 넣는다')
+  assert.equal(seqOf(h.state.cursor, KEY), 6, '커서가 구멍을 지나치지 않는다')
+  assert.match(String(out.detail), /6 다음이 7/)
+})
+
+test('★ 첫 봉투부터 구멍이면 아무것도 넣지 않고 커서도 그대로다', async () => {
+  const h = harness({ streams: { [KEY]: { seq: 4 } } })
+  const out = await run(h, async () => page([9, 10]))
+
+  assert.equal(out.stopped, 'gap')
+  assert.equal(out.applied, 0)
+  assert.equal(seqOf(h.state.cursor, KEY), 4)
+  assert.equal(h.state.ingested.length, 0, '넣을 것이 없는데 유입을 불렀다')
+})
+
+/* ── 상한 ─────────────────────────────────────────────────────────────────── */
+
+test('★ 쪽 상한에 닿으면 말한다 — 조용히 자르면 사람은 다 받은 줄로 읽는다', async () => {
+  const h = harness()
+  let n = 0
+  const out = await run(h, async () => page([++n]), 3)
+
+  assert.equal(out.stopped, 'page-limit')
+  assert.equal(out.pages, 3)
+  assert.match(String(out.detail), /남은 것이 있을 수 있다/)
+})
+
+/* ── 거절 ─────────────────────────────────────────────────────────────────── */
+
+test('★ backfill 이 실패하면 이유를 남기고 멈춘다 — 커서는 받은 데까지다', async () => {
+  const h = harness({ streams: { [KEY]: { seq: 4 } } })
+  const out = await run(h, async (_c: any, _s: any, _sc: string, since: number) => {
+    if (since === 4) return page([5])
+    throw new Error('MES 가 응답하지 않는다')
+  })
+
+  assert.equal(out.stopped, 'refused')
+  assert.match(String(out.detail), /응답하지 않는다/)
+  assert.equal(seqOf(h.state.cursor, KEY), 5, '받은 것은 지킨다')
+})
+
+test('★ 번호가 섞인 쪽은 받지 않는다 — 밀어 받는 길과 같은 검사를 지난다', async () => {
+  const h = harness()
+  const out = await run(h, async () => ({
+    scope: SCOPE,
+    items: [{ seq: 1, record: {} }, { record: {} }]
+  }))
+
+  assert.equal(out.stopped, 'refused')
+  assert.match(String(out.detail), /mixed batch/)
+  assert.equal(h.state.ingested.length, 0)
+})
+
+test('★ 커서 열쇠에 트윈이 들어간다 — 한 연결의 두 공장이 계수기를 함께 쓰지 않는다', async () => {
+  const other = pushCursorKey('twin-b', SCOPE)
+  const h = harness({ streams: { [KEY]: { seq: 4 }, [other]: { seq: 100 } } })
+  await run(h, async (_c: any, _s: any, _sc: string, since: number) => (since === 4 ? page([5]) : page([])))
+
+  assert.equal(seqOf(h.state.cursor, KEY), 5)
+  assert.equal(seqOf(h.state.cursor, other), 100, '다른 공장의 번호를 건드렸다')
+})
+
+/* ── 원본이 가진 번호 범위 ──────────────────────────────────────────────────── */
+
+test('★ 원본이 말한 번호 범위를 그대로 낸다 — 커서와 견주려면 이 값이 있어야 한다', async () => {
+  const got = await fillSince({
+    cfg: {},
+    site: { siteId: 's' },
+    scope: 'EVENTS',
+    cursorKey: 'i::EVENTS',
+    cursor: {},
+    fetch: async () => ({ items: [{ seq: 1, record: {} }], scope: 'EVENTS', sourceRange: { first: 1, last: 20 } }),
+    ingest: () => ({ applied: 1, duplicates: 0, rejected: [] }),
+    saveCursor: async () => {}
+  })
+  assert.deepEqual(got.sourceRange, { first: 1, last: 20 })
+})
+
+test('★ 원본이 안 말하면 그 칸을 안 낸다 — 0 으로 채우면 「다 받았다」가 된다', async () => {
+  /*
+   * 0 을 넣으면 「원본이 1번부터 다 갖고 있다」로 읽히고, 그것이 거짓이면 「우리가 다 받았다」는
+   * 잘못된 결론이 나온다. 견주는 쪽은 「맞다」가 아니라 「모른다」로 답해야 한다.
+   */
+  const got = await fillSince({
+    cfg: {},
+    site: { siteId: 's' },
+    scope: 'EVENTS',
+    cursorKey: 'i::EVENTS',
+    cursor: {},
+    fetch: async () => ({ items: [{ seq: 1, record: {} }], scope: 'EVENTS' }),
+    ingest: () => ({ applied: 1, duplicates: 0, rejected: [] }),
+    saveCursor: async () => {}
+  })
+  assert.equal(got.sourceRange, undefined)
+  assert.equal('sourceRange' in got, false, '없는 것을 undefined 로 실으면 화면이 칸을 그린다')
+})