@things-factory/headless-twin 10.0.19 → 10.1.0

package/server/service/reference/reference-fill.ts

@@ -0,0 +1,223 @@
+/*
+ * **놓친 구간을 backfill 해 채운다** — 밀어 받는 길의 짝.
+ *
+ * ── 왜 필요한가 (2026-08-31, 인티그레이션 레인 지적) ──────────────────────
+ * 훅은 반드시 놓친다 — 우리가 내려가 있을 때, 그쪽이 못 보냈을 때, 네트워크가 끊겼을 때. 받는 쪽이
+ * 번호로 그것을 **알아채게** 되었지만(§`takeInSequence`), 알아챈 뒤 **그 사이를 채우는 길이 없었다.**
+ * 설계가 그 길을 적어 두었는데 만들지 않았다.
+ *
+ * ── 같은 검사를 지난다 ───────────────────────────────────────────────────
+ * backfill 한 것도 `takeInSequence` 를 지난다. 여기서 따로 만들면 두 길이 다른 규칙으로 받고, 한쪽만
+ * 고쳐지는 날 어긋난 그 길에서만 사실이 사라진다.
+ *
+ * ── 멈추는 조건을 셋 둔다 ────────────────────────────────────────────────
+ * 되풀이해서 요청하는 경로는 **끝나지 않는 것**이 가장 흔한 결함이다.
+ *
+ *   빈 답        더 줄 것이 없다. 끝
+ *   번호가 안 나아간다  같은 것을 다시 받았다 — 무한히 요청하는 것을 막는다
+ *   구멍         원본의 아웃박스에 구멍이 있다. 이어 받으면 커서가 그 번호를 지나쳐 적힌다
+ *
+ * 그리고 **쪽 상한**을 둔다. 상한에 닿았으면 조용히 끝내지 않고 말한다 — 조용히 자르면 사람은 다 받은
+ * 줄로 읽는다.
+ */
+import { seqOf, takeInSequence, withSeq } from './hook-contract.js'
+import type { InboundBatch } from './reference-adapter.js'
+import { twinWarn } from '../../engine/log.js'
+
+/** 한 번 채우고 나서 남는 사실. */
+export interface FillOutcome {
+  /** 트윈에 넣은 레코드 수. */
+  applied: number
+  /**
+   * ingest 가 낸 네 갈래의 합 — **두 갈래로는 셈이 안 닫힌다.**
+   *
+   * ```
+   * 두 갈래   157 − 46 − 2 = 109 「설명 못 함」   진실은 되풀이 108 + 어휘 1
+   * 네 갈래   157 − 46 − 2 − 108 − 1 = 0
+   * ```
+   *
+   * 이 값이 없으면 원본 쪽에서 「보낸 것 20개 중 event 가 9개인데 나머지는 어디 갔나」를 셀 수
+   * 없다. 실제로 인티그레이션 레인이 그것을 물었고, 그 수가 트윈에 저장되지 않아 답을 못 했다.
+   */
+  duplicates: number
+  rejected: number
+  /**
+   * 왜 거절됐나 — **사유별 수.** 수만 내면 「26건이 안 들어온다」에서 멈춘다.
+   *
+   * 목록 전체가 아니라 사유별로 센다. 같은 이유로 거절된 26건이 26줄이면 읽는 사람이 그 줄을
+   * 세어야 하고, 다른 이유 하나가 그 안에 묻힌다.
+   */
+  rejectedReasons?: Record<string, number>
+  vocabulary: number
+  /** 시각을 못 읽어 ingest 시각으로 떨어진 것 — 종류별. 비어 있으면 전부 자기 시각을 말했다. */
+  undated?: Record<string, number>
+  /** 몇 쪽을 받았나. */
+  pages: number
+  /** 커서가 어디까지 갔나 — 아무것도 못 받았으면 없다. */
+  lastSeq?: number
+  /**
+   * 이 실행에서 **가장 낮게 받아들인 번호** — 밑에서부터 다시 받았을 때 이것이 곧 「우리가 가진
+   * 가장 낮은 번호」다.
+   */
+  lowestSeq?: number
+  /** 왜 멈췄나 — `done` · `gap` · `no-progress` · `page-limit` · `refused`. */
+  stopped: 'done' | 'gap' | 'no-progress' | 'page-limit' | 'refused'
+  /** 멈춘 이유의 사람 말. 알리지 않고 끝내지 않는다. */
+  detail?: string
+  /**
+   * 마지막으로 받은 묶음이 말한 **원본의 번호 범위** — 원본이 안 말하면 없다.
+   *
+   * 우리 커서와 견주는 자리가 이 값을 쓴다. 없으면 「맞다」가 아니라 **「모른다」**로 답해야 한다.
+   */
+  sourceRange?: { first?: number; last?: number }
+}
+
+/** 몇 쪽까지 받나 — 한 번의 채우기가 서버를 오래 붙잡지 않게. */
+const MAX_PAGES = 50
+
+/**
+ * 그 단위의 놓친 구간을 채운다.
+ *
+ * `ingest` 를 부르는 쪽이 넘겨 준다 — 훅과 같은 이유다(이 파일이 엔진을 직접 부르면 시험이 엔진을
+ * 세워야 한다).
+ */
+export async function fillSince(args: {
+  cfg: Record<string, any>
+  site: { siteId: string }
+  /** 번호를 매기는 단위 — 커서 열쇠의 절반. 커넥터가 만들지 않는다. */
+  scope: string
+  /** 커서에 적힌 열쇠 — `pushCursorKey(instanceId, scope)`. */
+  cursorKey: string
+  /** 지금 커서 — 이 함수가 읽고, 나아간 만큼 되돌려 준다. */
+  cursor: unknown
+  fetch: (cfg: Record<string, any>, site: { siteId: string }, scope: string, since: number) => Promise<InboundBatch>
+  ingest: (records: unknown[]) => { applied: number; duplicates: number; rejected: unknown[] }
+  /**
+   * 넣기 **직전에** 부른다 — 이 쪽의 레코드를 넘긴다.
+   *
+   * 중복 판정 기억을 저널에서 채우는 자리다(§`fill-dedupe.ts`). 그 기억은 프로세스 안에만 있어서
+   * 재기동하면 비워지고, 그러면 이미 저널에 있는 사실도 「처음 본 것」이 된다.
+   *
+   * `ingest` 는 동기라 여기서 채울 수 없다. 이 훅은 비동기이므로 저널을 읽을 수 있다.
+   *
+   * 실패해도 넣기를 멈추지 않는다 — 기억을 못 채운 것이 사실을 못 받을 이유는 아니다.
+   */
+  beforeIngest?: (records: unknown[]) => Promise<void>
+  saveCursor: (cursor: Record<string, unknown>) => Promise<void>
+  maxPages?: number
+}): Promise<FillOutcome> {
+  const { cfg, site, scope, cursorKey, fetch, ingest, saveCursor , beforeIngest } = args
+  const maxPages = args.maxPages ?? MAX_PAGES
+
+  let cursor = args.cursor
+  let applied = 0
+  let duplicates = 0
+  let rejectedCount = 0
+  const rejectedReasons: Record<string, number> = {}
+  let vocabulary = 0
+  const undated: Record<string, number> = {}
+  /* 원본이 말한 번호 범위 — 마지막으로 받은 묶음의 것을 들고 나간다. 안 말하면 끝까지 없다. */
+  let sourceRange: { first?: number; last?: number } | undefined
+  /* 이 실행에서 가장 낮게 받아들인 번호 — 커서에 firstSeq 로 적는다. */
+  let lowestSeq: number | undefined
+  let pages = 0
+
+  for (; pages < maxPages; pages++) {
+    const since = seqOf(cursor, cursorKey) ?? 0
+
+    let batch: InboundBatch
+    try {
+      batch = await fetch(cfg, site, scope, since)
+    } catch (e: any) {
+      return { applied, duplicates, rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}), vocabulary, ...(Object.keys(undated).length ? { undated } : {}), pages, ...seqPart(cursor, cursorKey), ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}), stopped: 'refused', detail: String(e?.message ?? e) }
+    }
+
+    if (batch?.sourceRange) sourceRange = batch.sourceRange
+
+    const items = batch?.items ?? []
+    /* 빈 답은 더 줄 것이 없다는 뜻이다. 오류가 아니다. */
+    if (!items.length) return { applied, duplicates, rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}), vocabulary, ...(Object.keys(undated).length ? { undated } : {}), pages, ...seqPart(cursor, cursorKey), ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}), stopped: 'done' }
+
+    const taken = takeInSequence({ items, scope, lastSeq: seqOf(cursor, cursorKey) })
+    if (taken.refused) {
+      return { applied, duplicates, rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}), vocabulary, ...(Object.keys(undated).length ? { undated } : {}), pages, ...seqPart(cursor, cursorKey), ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}), stopped: 'refused', detail: taken.refused }
+    }
+
+    if (taken.records.length) {
+      if (beforeIngest) {
+        await beforeIngest(taken.records).catch(e =>
+          twinWarn(`[twin-fill] 중복 판정 기억을 못 채웠다 — ${String(e?.message ?? e)}. 넣기는 그대로 간다`)
+        )
+      }
+      const result = ingest(taken.records)
+      applied += result.applied
+      duplicates += result.duplicates ?? 0
+      rejectedCount += result.rejected?.length ?? 0
+      for (const r of result.rejected ?? []) {
+        /* 사유가 여럿이면 첫 줄로 묶는다 — 뒤는 대개 같은 원인의 곁가지다. */
+        const why = String((r as any)?.errors?.[0] ?? '(사유 없음)').slice(0, 120)
+        rejectedReasons[why] = (rejectedReasons[why] ?? 0) + 1
+      }
+      vocabulary += (result as any).vocabulary ?? 0
+      for (const [k, n] of Object.entries((result as any).undated ?? {})) undated[k] = (undated[k] ?? 0) + (n as number)
+    }
+
+    /*
+     * **번호가 나아가야 다음 쪽을 요청한다.** 원본이 빈 묶음에 물어본 번호를 그대로 돌려주는 계약이면,
+     * 나아감을 보지 않고 요청하면 무한히 돈다.
+     */
+    if (taken.advancedSeq === undefined || taken.advancedSeq <= since) {
+      if (taken.gap) return { applied, duplicates, rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}), vocabulary, ...(Object.keys(undated).length ? { undated } : {}), pages: pages + 1, ...seqPart(cursor, cursorKey), ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}), stopped: 'gap', detail: gapWord(taken.gap) }
+      return {
+        applied,
+        duplicates,
+        rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}),
+        vocabulary,
+        ...(Object.keys(undated).length ? { undated } : {}),
+        pages: pages + 1,
+        ...seqPart(cursor, cursorKey),
+        ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}),
+        stopped: 'no-progress',
+        detail: `번호가 ${since} 에서 나아가지 않았다 — 같은 것을 다시 받았다`
+      }
+    }
+
+    if (lowestSeq === undefined) lowestSeq = taken.lowestSeq
+    /* 밑에서부터 다시 받았으면 그 번호가 곧 우리가 가진 가장 낮은 번호다. */
+    cursor = withSeq(cursor, cursorKey, taken.advancedSeq, taken.firstSeq ?? lowestSeq)
+    await saveCursor(cursor as Record<string, unknown>).catch(err =>
+      twinWarn(`[twin-fill] 번호를 커서에 적지 못했다 (${cursorKey}=${taken.advancedSeq}) — ${err?.message ?? err}`)
+    )
+
+    /*
+     * **구멍이 있으면 멈춘다.** 원본의 아웃박스에 구멍이 있는 것이고, 이어 받으면 커서가 그 번호를
+     * 지나쳐 적혀 빠진 사실이 다시 오지 않는다.
+     */
+    if (taken.gap) {
+      return { applied, duplicates, rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}), vocabulary, ...(Object.keys(undated).length ? { undated } : {}), pages: pages + 1, ...seqPart(cursor, cursorKey), ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}), stopped: 'gap', detail: gapWord(taken.gap) }
+    }
+  }
+
+  /* 상한에 닿았다 — 조용히 끝내지 않는다. 사람이 다 받은 줄로 읽으면 안 된다. */
+  return {
+    applied,
+    duplicates,
+    rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}),
+    vocabulary,
+    ...(Object.keys(undated).length ? { undated } : {}),
+    pages,
+    ...seqPart(cursor, cursorKey),
+    ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}),
+    stopped: 'page-limit',
+    detail: `${maxPages}쪽까지 받고 멈췄다 — 남은 것이 있을 수 있다. 다음 주기가 이어 받는다`
+  }
+}
+
+function seqPart(cursor: unknown, key: string): { lastSeq?: number } {
+  const seq = seqOf(cursor, key)
+  return seq === undefined ? {} : { lastSeq: seq }
+}
+
+function gapWord(gap: { expectedSeq: number; lastSeq: number }): string {
+  return `번호가 비었다 — ${gap.lastSeq} 다음이 ${gap.expectedSeq} 이어야 한다. 원본의 아웃박스에 구멍이 있다`
+}

package/server/service/reference/reference-hook.ts

@@ -42,12 +42,14 @@
  * 경계가 이미 거릅니다(§`FactDeduper`) — 이 파일이 따로 하지 않습니다. 응답에 몇 건이 중복이었는지
  * 함께 알립니다.
  */
-import { WEBHOOK_STATUS, checkSequence } from '@operato/ops-contract'
+import { WEBHOOK_STATUS, type WebhookResponse } from '@operato/ops-contract'
 
 import { twinWarn } from '../../engine/log.js'
 
 import { getAdapter, type InboundBatch } from './reference-adapter.js'
-import { authorizeHook, producedInstance, pushCursorKey, seqOf, withSeq, type HookOutcome } from './hook-contract.js'
+import { rejectedForCaller, type RejectedForCaller } from './hook-rejected.js'
+export { rejectedForCaller, type RejectedForCaller } from './hook-rejected.js'
+import { authorizeHook, producedInstance, pushCursorKey, seqOf, takeInSequence, withSeq, type HookOutcome } from './hook-contract.js'
 
 /**
  * 훅 하나를 처리한다 — 찾고 · 확인하고 · 커넥터에게 옮기게 하고 · 유입으로 넘긴다.
@@ -72,6 +74,15 @@ export async function handleHook(args: {
   nowMs?: number
   /** 레코드를 트윈에 넣는다 — 받은 수와 **떨어진 것들**을 돌려준다. */
   ingest: (instanceId: string, records: unknown[]) => IngestResult
+  /**
+   * 구멍을 봤다 — **부르는 쪽이 무엇을 할지 정한다.**
+   *
+   * 여기서 backfill 을 직접 부르지 않는다. 이 파일은 `ingest`·`store` 를 인자로 받아 가볍게 유지한다
+   * (그래야 테스트가 엔진 없이 이 판정을 확인할 수 있다). backfill 을 import 하면 그 규율이 깨진다.
+   *
+   * 기다리지 않는 것도 부르는 쪽의 몫이다 — 훅의 응답이 늦으면 보내는 쪽이 되풀이한다.
+   */
+  onGap?: (scope: string) => void
   /**
    * 저장소를 대신 쓰는 자리 — **시험이 재기동을 넣을 수 있게.**
    *
@@ -81,7 +92,7 @@ export async function handleHook(args: {
    */
   store: HookStore
 }): Promise<HookOutcome> {
-  const { domainId, source, instanceId, headers, body, rawBody, ingest } = args
+  const { domainId, source, instanceId, headers, body, rawBody, ingest, onGap } = args
   const nowMs = args.nowMs ?? Date.now()
   const { store } = args
 
@@ -142,62 +153,62 @@ export async function handleHook(args: {
    * **번호 확인** — 이 자리가 프레임워크인 이유는 밀어 주는 모든 연결에 같은 규율이라야 하기 때문이다.
    * 커넥터마다 만들면 한 곳이 빠지고, 빠진 그 연결에서만 사실이 없어진다.
    *
-   * 번호를 매기지 않는 원본(chef · ppms)은 `seq` 를 주지 않고, 그때는 확인하지 않는다. 확인하지 않았다는
-   * 것은 응답에 남긴다 — 「확인했고 이상 없다」와 구별되어야 한다.
+   * 판정은 `takeInSequence` 하나가 한다 — **backfill 하는 길도 같은 함수를 지난다.** 여기서 따로 만들면
+   * 두 길이 다른 규칙으로 받고, 한쪽만 고쳐지는 날이 온다.
    */
   const scope = typeof batch.scope === 'string' && batch.scope.trim() ? batch.scope.trim() : undefined
-  const withSeqCount = items.filter(i => typeof i?.seq === 'number').length
-  if (withSeqCount && withSeqCount !== items.length) {
-    /* 섞이면 빠진 것이 있는지 판단할 근거가 없다. 반쯤 확인한 것을 확인했다고 말하지 않는다. */
-    return {
-      status: WEBHOOK_STATUS.badPayload,
-      body: { ok: false, error: `mixed batch — ${withSeqCount} of ${items.length} items carry a sequence number` }
-    }
+  /* 열쇠에 트윈을 넣는다 — 연결 하나가 트윈 여럿을 만들고 커서는 연결마다 한 행이다. */
+  const key = scope ? pushCursorKey(instanceId, scope) : undefined
+  const taken = takeInSequence({
+    items,
+    scope,
+    lastSeq: key ? seqOf((ref as any).liveCursor, key) : undefined
+  })
+  if (taken.refused) {
+    /* 반쯤 확인한 것을 확인했다고 말하지 않는다. */
+    return { status: WEBHOOK_STATUS.badPayload, body: { ok: false, error: taken.refused } }
   }
-  const numbered = withSeqCount > 0 && scope !== undefined
-
+  const numbered = taken.numbered
+  const gap = taken.gap
   /*
-   * **첫 구멍에서 멈춘다.** 구멍 뒤의 봉투를 받아들이면 그 구멍이 영영 메워지지 않는다 — 보내는 쪽은
-   * `expectedSeq` 부터 다시 보내고, 뒤엣것은 그때 함께 온다.
+   * 첫 봉투가 1번이 아니면 **그 사실을 남긴다.** 커서가 없는 연결에 21번이 오면 커서가 21 로 뛰고,
+   * 그 앞 스무 건은 구멍으로도 안 세어진다. 실제로 plant 에서 그렇게 스무 건이 조용히 사라졌다.
+   *
+   * 손실이라고 말하지 않는다 — 늦게 붙은 트윈은 그 앞을 안 받기로 한 것이다. 수만 말하고 판단은
+   * 사람이 한다.
    */
-  let take = items.length
-  let advanced: { scope: string; seq: number } | undefined
-  let gap: { expectedSeq: number; lastSeq: number } | undefined
-  if (numbered) {
-    /* 열쇠에 트윈을 넣는다 — 연결 하나가 트윈 여럿을 만들고 커서는 연결마다 한 행이다. */
-    const key = pushCursorKey(instanceId, scope as string)
-    let cursor = seqOf((ref as any).liveCursor, key)
-    take = 0
-    for (const item of items) {
-      let verdict
-      try {
-        verdict = checkSequence(cursor, item.seq as number)
-      } catch (e: any) {
-        return { status: WEBHOOK_STATUS.badPayload, body: { ok: false, error: e?.message ?? 'bad sequence number' } }
-      }
-      if (verdict.kind === 'gap') {
-        gap = { expectedSeq: verdict.expectedSeq, lastSeq: verdict.lastSeq }
-        break
-      }
-      cursor = verdict.lastSeq
-      take++
-    }
-    /* 앞의 것을 하나도 못 받았으면 커서를 올릴 것이 없다. */
-    if (take > 0 && typeof cursor === 'number') advanced = { scope: key, seq: cursor }
+  if (taken.firstUnseenBefore) {
+    twinWarn(
+      `[twin-ingest] "${instanceId}" 의 ${scope ?? '(단위 없음)'} 를 ${taken.advancedSeq} 번부터 받기 시작했습니다 — ` +
+        `그 앞 ${taken.firstUnseenBefore}건은 받은 적이 없습니다. 원본이 오래 돌고 있었으면 정상이고, ` +
+        `보냈는데 못 받은 것이면 그만큼이 빠진 것입니다`
+    )
   }
+  const advanced = taken.advancedSeq !== undefined && key ? { scope: key, seq: taken.advancedSeq } : undefined
 
-  const records = items.slice(0, take).map(i => i.record)
+  const records = taken.records
 
   if (!records.length) {
     /*
      * 옮길 것이 없는 것은 오류가 아니다 — 그쪽이 우리와 무관한 것을 보낸 것일 수 있다. 다만 첫 봉투부터
      * 구멍이면 그것은 받은 것이 없는 것이고, 그 앞부터 달라고 해야 한다.
      */
-    if (gap) return gapOutcome(scope, gap)
-    if (advanced) await saveSeq(store, ref as any, advanced.scope, advanced.seq)
+    if (gap) {
+      if (scope) onGap?.(scope)
+      return gapOutcome(scope, gap)
+    }
+    if (advanced) await saveSeq(store, ref as any, advanced.scope, advanced.seq, taken.firstSeq)
     return {
       status: WEBHOOK_STATUS.ok,
-      body: { ok: true, offered: 0, applied: 0, duplicates: 0, rejected: [], ...seqBody(scope, advanced, numbered) }
+      body: {
+        ok: true,
+        offered: 0,
+        applied: 0,
+        duplicates: 0,
+        vocabulary: 0,
+        rejected: [],
+        ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)
+      }
     }
   }
 
@@ -208,15 +219,59 @@ export async function handleHook(args: {
     return { status: WEBHOOK_STATUS.failed, body: { ok: false, error: e?.message ?? 'ingest failed' } }
   }
   const rejected = result.rejected ?? []
+  /*
+   * ── 떨어진 것에 **봉투 id** 를 붙인다 (2026-09-07 측정) ──────────────────────
+   * 이 응답이 `{ record, errors }` 목록이었고, plant 은 그것을 **봉투 id 문자열 목록**으로 읽고
+   * 있었다. `Array.isArray` 는 통과하므로 그쪽 guard 도 안 걸렸다 — id 를 맞추는데 객체라 하나도
+   * 안 맞고 **묶음 전체가 「보냈음」으로 찍혔다.**
+   *
+   * 422 와 `ok: false` 를 보냈는데 그쪽 행은 재시도 0 · 오류 없음 · 보냈음이었다. 우리가 말했는데
+   * 상대가 못 알아듣는 모양이면, 말한 것이 아니다.
+   *
+   * 그래서 봉투 id 를 함께 싣는다. 보내는 쪽이 자기 행을 표시할 수 있고 까닭도 남는다.
+   *
+   * **id 를 못 찾으면 레코드를 그대로 싣는다.** 그때는 무엇이 떨어졌는지 알 방법이 그것뿐이고,
+   * 빈 id 를 실으면 보내는 쪽이 아무 행도 못 찾으면서 「알았다」고 여긴다.
+   *
+   * 짝은 **객체 동일성**으로 짓는다. `records` 는 `items` 의 순서와 원소를 그대로 들고 있고
+   * (§`takeInSequence`), 그래서 커넥터를 고치지 않고도 봉투로 되짚을 수 있다. 값으로 비교하면
+   * 같은 모양의 레코드 둘이 서로의 id 를 가져간다.
+   */
+  const forCaller = rejectedForCaller(rejected, items as { record?: unknown; eventId?: unknown }[])
 
-  if (result.applied === 0 && result.duplicates === 0 && rejected.length === 0) {
+  if (result.applied === 0 && result.duplicates === 0 && rejected.length === 0 && !result.vocabulary) {
     /*
      * 넣었는데 한 건도 반영되지 않았고 중복도 거부도 아니면, 그 트윈이 실시간으로 돌지 않는 것이다.
      * 200 을 주면 그쪽은 전달된 줄 알고 그 사실을 버린다.
      *
      * **커서를 올리지 않는다.** 한 건도 안 들어갔는데 번호를 올리면 그 번호는 다시 오지 않고, 트윈이
      * 뜬 뒤에 그 구간이 비어 있게 된다.
+     *
+     * ── Vocabulary is why this test needs a fourth term (2026-09-07) ──────────
+     * This inference reads an absence as a cause, and one absence is legitimate: a batch that was
+     * entirely vocabulary applies no events, has no duplicates and rejects nothing, and yet
+     * everything in it landed (§`applyMasterData`). Without the last term the receiver answers
+     * 503 to correct traffic, and the sender then holds those facts and retries every thirty
+     * seconds for as long as they keep arriving — the reply invents a reason ("not running live")
+     * that the numbers do not support.
+     *
+     * Found by a test written for the response sum, not by reading this line.
+     *
+     * ── Why this branch has to say something out loud ─────────────────────────
+     * Measured today: a 503 from here leaves **no trace on either side.** The sender maps it to
+     * backpressure and returns without touching `attempts` or `lastError`, and this branch logged
+     * nothing, so a sender re-offering the same batch every thirty seconds is invisible to both.
+     *
+     * That is also why "it has not happened" could not be established: `attempts 0` on the seven
+     * vocabulary envelopes was offered as evidence and is not evidence, because this path never
+     * increments that counter. Telling a sender to come back forever is worth one line.
      */
+    twinWarn(
+      `[twin-hook] "${instanceId}" 에 ${records.length}건이 왔는데 한 건도 앉지 않아 ` +
+        `${NOT_LIVE_RETRY_MS / 1000}초 뒤 다시 오라고 답했습니다 — 트윈이 실시간으로 돌지 않는 것으로 봅니다. ` +
+        `보내는 쪽은 이 답에 재시도 횟수를 남기지 않으므로, 되풀이되면 이 줄만 늘어납니다`
+    )
+
     return {
       status: WEBHOOK_STATUS.notLive,
       body: {
@@ -228,13 +283,16 @@ export async function handleHook(args: {
     }
   }
 
-  if (advanced) await saveSeq(store, ref as any, advanced.scope, advanced.seq)
+  if (advanced) await saveSeq(store, ref as any, advanced.scope, advanced.seq, taken.firstSeq)
 
   /*
    * **구멍이 있으면 그것이 답을 정한다.** 앞의 것은 이미 들어갔으므로 `lastSeq` 까지는 보냄으로 표시하게
    * 하고, 떨어진 것이 있으면 그것도 함께 싣는다 — 두 소식이 한 응답에 들어가야 보내는 쪽이 둘 다 한다.
    */
-  if (gap) return gapOutcome(scope, gap, rejected, advanced)
+  if (gap) {
+    if (scope) onGap?.(scope)
+    return gapOutcome(scope, gap, forCaller, advanced)
+  }
 
   if (rejected.length) {
     /*
@@ -249,8 +307,9 @@ export async function handleHook(args: {
         offered: records.length,
         applied: result.applied,
         duplicates: result.duplicates,
-        rejected,
-        ...seqBody(scope, advanced, numbered)
+        vocabulary: result.vocabulary ?? 0,
+        rejected: forCaller,
+        ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)
       }
     }
   }
@@ -262,8 +321,14 @@ export async function handleHook(args: {
       offered: records.length,
       applied: result.applied,
       duplicates: result.duplicates,
+      /*
+       * Always reported, even as zero — the sender's sum has a term for it either way, and a field
+       * that appears only sometimes makes an absent one indistinguishable from a receiver that
+       * does not count vocabulary at all.
+       */
+      vocabulary: result.vocabulary ?? 0,
       rejected: [],
-      ...seqBody(scope, advanced, numbered)
+      ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)
     }
   }
 }
@@ -278,6 +343,18 @@ export interface IngestResult {
   applied: number
   duplicates: number
   rejected: { record: unknown; errors: string[] }[]
+  /**
+   * How many records were vocabulary rather than events — **needed so the reply's sum closes.**
+   *
+   * `liveIngest` has counted this all along and this boundary dropped it, because the callback was
+   * typed as `IngestResult` and vocabulary was not on it. So `offered` counted those records and
+   * none of the other three did, and a sender checking the sum would have seen a loss on ordinary
+   * traffic (§`WebhookResponse.offered`).
+   *
+   * Optional because an ingest that handles no vocabulary need not say zero, and a caller that
+   * simply does not know must not be made to claim none.
+   */
+  vocabulary?: number
 }
 
 /**
@@ -286,10 +363,21 @@ export interface IngestResult {
  * `lastSeq` 를 빼면 보내는 쪽은 이미 들어간 것까지 다시 보내고, 그것이 매번 중복으로 걸러지면서
  * 처리량만 먹는다.
  */
+/*
+ * 구멍을 본 자리에서 **바로 받는다** — 번호가 비었다는 것을 아는 가장 이른 순간이다.
+ *
+ * 기다리지 않는다. 훅의 응답이 이것 때문에 늦으면 보내는 쪽이 되풀이하고, 그러면 같은 봉투가 두 번
+ * 온다. 그리고 같은 단위를 1분 안에 두 번 부르지 않는다(§`FILL_DEBOUNCE_MS`) — 밀어 받는 쪽이
+ * 구멍 뒤의 봉투를 계속 보내면 그때마다 구멍 판정이 나기 때문이다.
+ */
 function gapOutcome(
   scope: string | undefined,
   gap: { expectedSeq: number; lastSeq: number },
-  rejected: { record: unknown; errors: string[] }[] = [],
+  /*
+   * 떨어진 것 — 봉투 id 를 알면 그것을, 모르면 레코드를 싣는다(§`InboundItem.eventId`).
+   * 보내는 쪽이 자기 행을 찾을 수 있어야 하고, 못 찾으면 무엇이 떨어졌는지라도 보여야 한다.
+   */
+  rejected: RejectedForCaller[] = [],
   advanced?: { scope: string; seq: number }
 ): HookOutcome {
   return {
@@ -319,13 +407,30 @@ const NOT_LIVE_RETRY_MS = 30_000
  * 번호를 매기지 않는 원본은 확인할 것이 없다. 그것을 응답에서 「이상 없다」와 같아 보이게 두면, 어느
  * 연결이 연속성을 지키고 있는지 아무도 알 수 없다.
  */
+/*
+ * The return type is the contract's, narrowed to the fields this function fills.
+ *
+ * It was `Record<string, unknown>`, and because the result is **spread** into the reply, an index
+ * signature slips past the excess-property check entirely — the four fields below were unverified
+ * even after `HookOutcome.body` was typed. Naming them here is what makes the check reach them.
+ */
 function seqBody(
   scope: string | undefined,
   advanced: { scope: string; seq: number } | undefined,
-  numbered: boolean
-): Record<string, unknown> {
+  numbered: boolean,
+  firstUnseenBefore?: number
+): Pick<WebhookResponse, 'sequenceChecked' | 'scope' | 'lastSeq' | 'firstUnseenBefore'> {
   if (!numbered) return { sequenceChecked: false }
-  return { sequenceChecked: true, scope, lastSeq: advanced?.seq }
+  return {
+    sequenceChecked: true,
+    scope,
+    lastSeq: advanced?.seq,
+    /*
+     * 첫 봉투였고 그 앞을 못 봤으면 **그 수를 보내는 쪽에 돌려준다.** 안 돌려주면 그 사실이 아무 데도
+     * 안 남는다 — 구멍으로도 안 세어지고 backfill 대상도 아니다(backfill 은 커서부터 묻는다).
+     */
+    ...(firstUnseenBefore ? { firstUnseenBefore } : {})
+  }
 }
 
 /**
@@ -341,9 +446,10 @@ async function saveSeq(
   store: HookStore,
   ref: { id: string; liveCursor?: unknown },
   scope: string,
-  seq: number
+  seq: number,
+  firstSeq?: number
 ): Promise<void> {
-  const next = withSeq(ref.liveCursor, scope, seq)
+  const next = withSeq(ref.liveCursor, scope, seq, firstSeq)
   ref.liveCursor = next
   await store
     .saveCursor(ref.id, next)

package/server/service/reference/reference-link-groups.ts

@@ -0,0 +1,21 @@
+/*
+ * 원본이 준 관계 그룹 중 화면에 낼 수 있는 것만 남기는 판정.
+ *
+ * 조회 코드(`reference-links.ts`)와 나누어 둔다. 그쪽은 TypeORM 엔티티를 물어서 테스트 프로세스가
+ * 적재할 수 없다. 판정만 따로 두면 테스트가 가벼운 import 로 확인할 수 있다.
+ */
+import type { ExternalIncoming } from '../twin-model/external-resolver.js'
+
+/**
+ * 이름(`via`)이 없으면 화면에 이름 없는 줄이 된다. `total` 이 0 이면 낼 내용이 없다 — 원본이 그
+ * 축을 취급하지 않는다는 뜻이고, 트윈이 선언한 관계가 비어 있는 것과 다르다. 후자는 그대로
+ * 표시한다(`twin-model-item-query.ts`).
+ *
+ * `total` 이 없는 그룹도 버린다. 목록만 보내고 전체 수를 빼면 화면이 목록 길이를 전체 수로 쓰게
+ * 되고, 원본이 20개만 보낸 날 실제 200건이 20건으로 표시된다.
+ */
+export function usableLinkGroups(groups: ExternalIncoming[] | undefined | null): ExternalIncoming[] {
+  return (groups ?? []).filter(
+    g => !!g && typeof g.via === 'string' && !!g.via.trim() && typeof g.total === 'number' && g.total > 0
+  )
+}

package/server/service/reference/reference-links.ts

@@ -0,0 +1,77 @@
+/*
+ * **원본에만 있는 관계를 조회해서 트윈 상세 화면에 붙인다.**
+ *
+ * ── 무엇을 해결하나 ────────────────────────────────────────────────────────
+ * 설비 상세 화면에서 사람이 실제로 묻는 것은 「이 설비로 무엇을 얼마나 만들었나」, 「지금 정비
+ * 중인가」, 「예정된 정비가 있나」다. 그 정보는 트윈에 없고 MES 에 있다.
+ *
+ * 트윈으로 복제하면 원본의 테이블을 전부 미러링하게 됩니다. 조회용 참조는 복제하지 않고 필요할 때
+ * 물어보는 것이 맞습니다.
+ *
+ * ── 왜 프로세스가 나뉘어 있는가 ────────────────────────────────────────────
+ * 측정 결과입니다(2026-09-06).
+ *
+ *   operato-plant   포트 4000   자기 DB
+ *   operato-twin    포트 3000   자기 DB
+ *
+ * 별개 프로세스이므로 plant 안에서 `registerExternalResolver` 를 불러도 twin 프로세스에는 등록되지
+ * 않습니다. 그래서 resolver 는 twin 안에 있고, 본체는 어댑터를 통해 원본에 HTTP 로 물어봅니다.
+ *
+ * 주소와 인증은 이미 연결 설정(`TwinReference.connectionConfig`)에 있습니다. 새로 만들 것이 없습니다.
+ *
+ * ── 왜 부팅에 한 번만 등록하나 ──────────────────────────────────────────────
+ * 연결은 나중에 추가될 수 있습니다. 연결마다 resolver 를 등록하면 새 연결이 생길 때 재기동해야
+ * 합니다. resolver 하나가 호출될 때 연결을 조회하므로 재기동이 필요 없습니다.
+ */
+import { getRepository } from '@things-factory/shell'
+
+import { TwinInstance } from '../twin-instance/twin-instance.js'
+import { TwinReference } from './twin-reference.js'
+import { getAdapter, type SiteDescriptor } from './reference-adapter.js'
+import { registerExternalResolver, type ExternalIncoming } from '../twin-model/external-resolver.js'
+import { usableLinkGroups } from './reference-link-groups.js'
+
+/**
+ * 이 트윈의 원본에 관계를 물어본다.
+ *
+ * 물어볼 수 없는 경우가 여럿이고 **전부 빈 배열입니다** — 원본을 모르는 트윈, 등록되지 않은 어댑터,
+ * `fetchLinks` 를 구현하지 않은 어댑터. 이 셋은 결함이 아닙니다. 가상 원본과 시뮬레이터는 조회할
+ * 관계가 없습니다.
+ *
+ * 실패는 다릅니다 — 예외를 그대로 올립니다. 호출하는 쪽(`externalIncoming`)이 잡아서 경고를 남기고
+ * 나머지 관계는 그대로 표시합니다.
+ */
+export async function fetchReferenceLinks(
+  domainId: string,
+  instanceId: string,
+  axis: string,
+  itemId: string
+): Promise<ExternalIncoming[]> {
+  const ref = await getRepository(TwinReference).findOne({ where: { domain: { id: domainId }, source: instanceId } })
+  if (!ref) return []
+
+  const adapter = getAdapter(ref.adapterType)
+  if (!adapter?.fetchLinks) return []
+
+  /*
+   * 사이트를 함께 넘깁니다 — 원본 하나가 여러 사이트를 낼 수 있습니다(`discoverSites`). 이 트윈이
+   * 어느 사이트에서 왔는지는 `origin.siteId` 에 있고, 없으면 넘기지 않습니다.
+   */
+  const inst = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })
+  const siteId = (inst?.origin as any)?.siteId
+  const site: SiteDescriptor | undefined = siteId ? { siteId } : undefined
+
+  return usableLinkGroups(await adapter.fetchLinks(ref.connectionConfig ?? {}, site, axis, itemId))
+}
+
+/** 부팅에서 한 번 등록한다. */
+export function installReferenceLinkResolver(): void {
+  registerExternalResolver({
+    /*
+     * `entity` 는 계약의 `target.entity` 와 맞추는 값입니다. 이 resolver 는 들어오는 관계만 답하고
+     * 특정 관계에 붙지 않으므로, 계약에 없는 이름을 씁니다.
+     */
+    entity: 'reference.links',
+    incoming: (domainId, instanceId, axis, itemId) => fetchReferenceLinks(domainId, instanceId, axis, itemId)
+  })
+}