@things-factory/headless-twin 10.1.278 → 10.1.280

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

@@ -1,250 +0,0 @@
-import type { IngestWarning, ReferenceMaster } from './reference-master.js'
-
-/*
- * **원본에서 읽은 뒤의 총평** — 사람이 한 장으로 읽는다.
- *
- * ── 왜 필요한가 (2026-08-22) ────────────────────────────────────────────────
- * 읽기가 끝나면 화면에 남는 것은 경고 열 줄이었고, 그 안에 이유가 문장으로 묻혀 있고 UUID 수백 개가
- * 붙어 있었다. 그래서 사람이 「가져올 것은 다 들어왔나」·「무엇이 비었나」·「다음에 무엇을 하면
- * 나아지나」를 스스로 세어야 했다 — 실제로 그 셋을 손으로 세는 대화가 하루를 채웠다.
- *
- * 그 셋은 이미 우리가 아는 사실이다. 세어 두었으니 **정리해서 내면 된다.**
- *
- * ── 두 층으로 나눈다 ────────────────────────────────────────────────────────
- * 여기는 **사실 층**이다: 센 것과 그 사유 코드만 담고 문장을 만들지 않는다. 화면이 표로 그리고,
- * 사람이 더 알고 싶으면 그때 AI 가 이 사실**만** 근거로 서술한다(말 층).
- *
- * **AI 는 로드베어링이 아니다.** 호출이 꺼져 있거나 실패해도 이 표가 그대로 화면에 남아야 한다 —
- * 그래서 사실 층이 스스로 완결이다.
- *
- * ── 무엇을 지어내지 않는가 ──────────────────────────────────────────────────
- * 「없음」의 뜻을 셋으로 구분해 둔다. 뭉치면 조치가 달라지는 것들이 한 칸에 섞인다.
- *  · `gaps` — 원본에 있는데 우리가 옮기지 못했다. 고칠 대상이 있다(원본의 빈 칸이거나 우리 매핑).
- *  · `absent` — 이 원본에 그 **개념이 없다.** 빠진 것이 아니므로 고칠 것이 없다.
- *  · `grounding` — 값이 들어왔지만 **근거가 저장된 값이 아니다**(원본의 계산 규칙에서 왔다).
- */
-
-/** 센 것 — 화면이 그대로 표로 그린다. */
-export interface AssessmentCounts {
-  locations: number
-  areas: number
-  equipment: number
-  materialDefinitions: number
-  operations: number
-  /** 생산 선언이 없으면 없다 — 0 과 구별한다(선언 자체가 없는 것과 비어 있는 것은 다르다). */
-  materials?: number
-  materialsWithHome?: number
-  routes?: number
-  recipes?: number
-  recipesWithRoute?: number
-  /** 공정을 말하는 투입 / 전체 투입 — 공정별 소요를 아는 정도. */
-  taggedInputs?: number
-  totalInputs?: number
-  /** 시험 명세(점검표)의 수 — 선언되지 않았으면 없다(0 과 구별한다). */
-  testSpecifications?: number
-  /** 그 명세들이 선언한 판정 기준의 수. */
-  criteria?: number
-  /**
-   * 그중 **아무 한계도 말하지 않는** 기준의 수 — 커널의 `criterionSaysNothing` 과 같은 판정이다.
-   *
-   * 이 수가 0 이 아니면 「관리점이 있다」가 「판정된다」를 뜻하지 않는다. 세지 않으면 그 구별이 사라진다.
-   */
-  criteriaWithoutLimit?: number
-}
-
-/** 옮기지 못한 것 한 갈래 — 건수 큰 것부터. */
-export interface AssessmentGap {
-  /** 무엇을 옮기다 못 옮겼나 — 커넥터가 붙인 이름(`material home warehouse`). */
-  what: string
-  count: number
-  /** 못 옮긴 원본 값 몇 개 — 전부가 아니라 표본이다(수백 개가 붙던 자리다). */
-  sample?: string
-  /** 그 자리에 대신 들어간 값. */
-  fallback?: string
-}
-
-export interface ImportAssessment {
-  source: string
-  siteId: string
-  siteName?: string
-  system?: string
-  built: AssessmentCounts
-  /**
-   * **원본이 가지고 있던 수** — 커넥터가 말해 준 경우에만 있다.
-   *
-   * 이름을 `origin` 이라 하지 않는다 — 화면에서 그 낱말이 이미 **트윈의 출처**(`summary.origin`:
-   * 템플릿인가 원본인가)를 뜻한다. 같은 이름을 두 뜻으로 쓰면 읽는 사람이 헷갈린다.
-   *
-   * `built` 와 비교해 「전부 옮겼는가」를 사람이 직접 셀 수 있게 한다. 커넥터가 말하지 않으면 이 자리는
-   * 비어 있고, 화면은 분모 없이 옮긴 수만 보인다 — **분모를 지어내지 않는다.**
-   */
-  originCounts?: Record<string, number>
-  gaps: AssessmentGap[]
-  /** 이 원본에 개념이 없는 자리 — 커널 낱말로 적는다(화면이 번역한다). */
-  absent: string[]
-  /**
-   * 값이 들어왔지만 **근거가 원본의 저장된 값이 아닌 것** — 파생·유추된 값이다.
-   *
-   * 이것을 `gaps` 에 섞으면 안 된다. 빈 자리가 아니라 **채워진 자리**이고, 사람이 물을 것은
-   * 「왜 비었나」가 아니라 「그 값을 믿어도 되나」다. 조치도 다르다 — 원본을 채우는 것이 아니라
-   * 그 규칙이 바뀌면 이 값도 바뀐다는 사실을 아는 것이다.
-   */
-  derived: AssessmentGap[]
-  /** 되물은 횟수·잘린 목록 같은 운영 사실. */
-  notes: IngestWarning[]
-}
-
-/** 이 마스터가 개념을 선언했나 — 「없다」와 「비어 있다」를 구분한다. */
-const declared = (v: unknown): boolean => Array.isArray(v) ? v.length > 0 : v !== undefined && v !== null
-
-/**
- * 마스터 한 벌 → 총평의 사실 층.
- *
- * 경고를 두 갈래로 나눈다: `connector-mapping-fallback` 은 **옮기지 못한 것**이므로 `gaps` 로,
- * 나머지(파생된 값·되물은 횟수·잘린 목록)는 `notes` 로 그대로 나른다. 판단하지 않는다 — 무엇이
- * 심각한지는 건수와 그 자리의 뜻이 말하고, 그 해석은 사람이나 말 층의 몫이다.
- */
-export function assessMaster(master: ReferenceMaster, siteId: string): ImportAssessment {
-  const m: any = master
-  const d = m.productionSpec?.definition
-  const inputs = (d?.recipes ?? []).flatMap((r: any) => r.inputs ?? [])
-
-  const built: AssessmentCounts = {
-    locations: (m.locations ?? []).length,
-    areas: (m.locations ?? []).filter((l: any) => l.role === 'area' || l.role === 'both').length,
-    equipment: (m.equipment ?? []).length,
-    materialDefinitions: (m.materialDefinitions ?? []).length,
-    operations: (m.operations ?? []).length,
-    ...(declared(m.testSpecifications)
-      ? {
-          testSpecifications: m.testSpecifications!.length,
-          criteria: m.testSpecifications!.reduce((n, t) => n + (t.criteria?.length ?? 0), 0),
-          /*
-           * **한계를 말하지 않는 기준** — 커널의 `criterionSaysNothing` 과 같은 판정이다. 기준이
-           * 선언됐다는 사실만 있고 판정할 재료가 없는 자리이고, 그것을 세지 않으면 「관리점이 있다」가
-           * 「판정된다」로 읽힌다.
-           */
-          criteriaWithoutLimit: m.testSpecifications!.reduce(
-            (n, t) => n + (t.criteria ?? []).filter(c => !c.expression && c.limit?.minimum === undefined && c.limit?.maximum === undefined).length,
-            0
-          )
-        }
-      : {}),
-    ...(d
-      ? {
-          materials: (d.materials ?? []).length,
-          materialsWithHome: (d.materials ?? []).filter((x: any) => x.locationType).length,
-          routes: (d.routes ?? []).length,
-          recipes: (d.recipes ?? []).length,
-          recipesWithRoute: (d.recipes ?? []).filter((x: any) => x.route).length,
-          totalInputs: inputs.length,
-          taggedInputs: inputs.filter((i: any) => i.operation).length
-        }
-      : {})
-  }
-
-  /* 원본의 수는 커넥터가 말한 그대로 나른다 — 여기서 고치거나 채우지 않는다. */
-  const originCounts = m.originCounts && Object.keys(m.originCounts).length ? { ...m.originCounts } : undefined
-
-  const gaps: AssessmentGap[] = []
-  const derived: AssessmentGap[] = []
-  const notes: IngestWarning[] = []
-  /*
-   * 커넥터가 「대체」 수집기로 남기는 것 중 일부는 **빈 자리가 아니라 파생된 값**이다(산출량이 원본의
-   * 계산 규칙에서 온 경우처럼). 같은 통로로 오지만 뜻이 달라 구분해 담는다 — 이름에 그 사실이 적혀 있다.
-   */
-  const isDerived = (field: string) => /derived|not a stored field/i.test(field)
-  for (const w of m.warnings ?? []) {
-    if (w?.code === 'connector-mapping-fallback' && w.params?.field) {
-      const values = String(w.params.values ?? '')
-      const bin = isDerived(String(w.params.field)) ? derived : gaps
-      bin.push({
-        what: String(w.params.field),
-        count: Number(w.params.count ?? 0),
-        /* 값은 표본만 — 이 자리에 UUID 수백 개가 붙어 화면을 밀어냈다. 전체는 경고 원문에 남는다. */
-        ...(values ? { sample: values.length > 120 ? `${values.slice(0, 120)}…` : values } : {}),
-        ...(w.params.fallback ? { fallback: String(w.params.fallback) } : {})
-      })
-      continue
-    }
-    notes.push(w)
-  }
-  gaps.sort((a, b) => b.count - a.count)
-  derived.sort((a, b) => b.count - a.count)
-
-  /*
-   * 이 원본에 개념이 없는 자리. **커널 낱말로 적는다** — 화면이 그것으로 번역하고, 개념 지도가 이미
-   * 같은 낱말을 쓴다(두 화면이 다른 말을 하면 사람이 둘을 다른 사실로 읽는다).
-   */
-  const absent: string[] = []
-  if (!declared(m.persons)) absent.push('persons')
-  if (!declared(m.assets)) absent.push('assets')
-  if (!declared(m.testSpecifications)) absent.push('testSpecifications')
-  if (!declared(m.personnelClasses)) absent.push('personnelClasses')
-  if (!declared(m.assetClasses)) absent.push('assetClasses')
-  if (!declared(m.materialClasses)) absent.push('materialClasses')
-  if (!d) absent.push('productionSpec')
-
-  return {
-    source: m.source,
-    siteId,
-    siteName: m.siteName,
-    system: m.system,
-    built,
-    ...(originCounts ? { originCounts } : {}),
-    gaps,
-    derived,
-    absent,
-    notes
-  }
-}
-
-/** 사람이 읽는 줄 — 터미널·로그가 읽는다(화면은 구조를 그대로 그린다). */
-export function formatAssessment(a: ImportAssessment): string {
-  const c = a.built
-  const out: string[] = []
-  /**
-   * 분모가 있으면 함께 적는다 — 「1,261」과 「원본 1,408 중 1,261」은 다른 말이다.
-   * 커넥터가 그 수를 말하지 않았으면 옮긴 수만 적는다(지어내지 않는다).
-   */
-  const n = (key: keyof AssessmentCounts, v?: number) => {
-    if (v === undefined) return '없음'
-    const o = a.originCounts?.[key as string]
-    return o === undefined ? String(v) : o === v ? `${v}(원본 전부)` : `${v} / 원본 ${o}`
-  }
-  out.push(`총평 ${a.siteName ?? a.siteId} (${a.system ?? '?'}) — 원본 ${a.source}`)
-  out.push(
-    `  선 것: 로케이션 ${n('locations', c.locations)}(존 ${c.areas}) · 설비 ${n('equipment', c.equipment)} · ` +
-      `품목 정의 ${n('materialDefinitions', c.materialDefinitions)} · 공정 ${n('operations', c.operations)}`
-  )
-  if (c.materials !== undefined) {
-    out.push(
-      `         자재 ${n('materials', c.materials)}(보관 로케이션 있는 것 ${c.materialsWithHome}) · ` +
-        `경로 ${n('routes', c.routes)} · 레시피 ${n('recipes', c.recipes)}(경로 붙은 것 ${c.recipesWithRoute}) · ` +
-        `투입 ${n('totalInputs', c.totalInputs)}(공정을 말하는 것 ${c.taggedInputs})`
-    )
-  } else {
-    out.push('         생산 선언 없음 — 레시피가 하나도 성립하지 않았다')
-  }
-  if (a.gaps.length) {
-    out.push('  옮기지 못한 것(건수 순):')
-    for (const g of a.gaps) out.push(`    ${String(g.count).padStart(6)}  ${g.what}${g.sample ? ` — ${g.sample}` : ''}`)
-  }
-  if (a.derived.length) {
-    out.push('  파생된 값(저장된 값이 아니다):')
-    for (const g of a.derived) out.push(`    ${g.what}${g.sample ? ` — ${g.sample}` : ''}`)
-  }
-  if (c.testSpecifications) {
-    /*
-     * 관리 기준은 계측이 오는지와 무관하게 값이 있다 — 「관리점이 셋인데 둘은 아무 한계도 말하지
-     * 않는다」를 여기서 볼 수 있어야 판정에 근거가 있는지 사람이 안다.
-     */
-    out.push(
-      `  관리 기준: 점검표 ${n('testSpecifications', c.testSpecifications)} · 기준 ${c.criteria ?? 0}` +
-        (c.criteriaWithoutLimit ? ` (한계를 말하지 않는 것 ${c.criteriaWithoutLimit})` : '')
-    )
-  }
-  if (a.absent.length) out.push(`  이 원본에 개념이 없는 자리: ${a.absent.join(', ')}`)
-  for (const n of a.notes) out.push(`  참고 ${n.code}: ${n.message}`)
-  return out.join('\n')
-}

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

@@ -1,179 +0,0 @@
-/*
- * **빠진 구간을 다시 받는 일을 실제로 부른다** — `fillSince` 에 연결과 어댑터를 물려 주는 자리.
- *
- * ── 왜 이 파일이 없었나 ─────────────────────────────────────────────────────
- * `fillSince` 는 2026-08-31 에 만들어졌고 **부르는 곳이 0곳이었습니다.** 2026-09-05 에 저는 그것을
- * 못 보고 같은 일을 하는 것을 하나 더 만들었습니다(`backfillScope`). 두 벌이 되었고 둘 다 아무도
- * 부르지 않았습니다.
- *
- * 그래서 이런 상태였습니다.
- *
- * ```
- * 번호가 비면 어디서부터 다시 받을지 안다   ✔  takeInSequence 가 판정한다
- * 그 빈 것을 메운다                        ✖  부를 곳이 없다
- * ```
- *
- * 실제로 plant 아웃박스의 1~20 을 잃고 되찾을 방법이 없는 상태를 만났습니다.
- *
- * ── 같은 검사를 지난다 ──────────────────────────────────────────────────────
- * `fillSince` 가 `takeInSequence` 를 지나고, 유입은 `liveIngest` 를 지납니다 — 밀어 받는 길과 같은
- * 함수입니다. 여기서 따로 만들면 두 길이 다른 규칙으로 받고, 한쪽만 수정되는 날이 옵니다.
- *
- * ── 커서 열쇠는 프레임워크가 만든다 ─────────────────────────────────────────
- * 열쇠는 `instanceId::scope` 이고 그것을 아는 것은 프레임워크입니다. 어댑터가 만들면 두 곳이 같은
- * 규칙을 갖게 되고, 어긋나는 날 **다시 받기가 자기 커서를 0부터 새로 셉니다.**
- */
-import { getRepository } from '@things-factory/shell'
-
-import { TwinInstance } from '../twin-instance/twin-instance.js'
-import { TwinReference } from './twin-reference.js'
-import { getAdapter, type SeqReport, type SiteDescriptor } from './reference-adapter.js'
-import { firstSeqOf, pushCursorKey, seqOf, withSeq } from './hook-contract.js'
-import { fillSince, type FillOutcome } from './reference-fill.js'
-import { liveIngest } from './live-ingest.js'
-import { recordReferenceReconciliation } from './reference-reconciliation-writer.js'
-import { journalIdentities, spanOf } from './fill-dedupe.js'
-import { TwinEngine } from '../../engine/index.js'
-import { twinLog, twinWarn } from '../../engine/log.js'
-
-/** 한 연결의 한 단위를 다시 받은 결과. */
-export interface FillRunResult extends Partial<FillOutcome> {
-  instanceId: string
-  scope: string
-  /**
-   * 못 한 이유 — 성공이면 없습니다.
-   *
-   * `not-supported` 는 결함이 아닙니다. 주기로 물어보는 원본(chef · ppms)은 다음 주기가 곧 다시
-   * 받는 것입니다.
-   */
-  skipped?: 'unknown-twin' | 'no-source' | 'no-adapter' | 'not-supported'
-}
-
-/**
- * 그 연결의 한 단위를 다시 받는다.
- *
- * **커서를 되돌리지 않습니다.** 받은 것이 번호 검사를 지나야 커서가 나아가고, 그 판정은 밀어 받는
- * 길과 같은 함수가 합니다.
- *
- * @param from 여기서부터 다시 받는다 — 주면 커서를 무시합니다. 잃은 구간을 되찾을 때만 씁니다.
- */
-export async function runFill(args: {
-  domainId: string
-  instanceId: string
-  scope: string
-  from?: number
-  maxPages?: number
-}): Promise<FillRunResult> {
-  const { domainId, instanceId, scope, from, maxPages } = args
-  const base: FillRunResult = { instanceId, scope }
-
-  const inst = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })
-  if (!inst) return { ...base, skipped: 'unknown-twin' }
-
-  const repo = getRepository(TwinReference)
-  const ref = await repo.findOne({ where: { domain: { id: domainId }, source: instanceId } })
-  if (!ref) return { ...base, skipped: 'no-source' }
-
-  const adapter = getAdapter(ref.adapterType)
-  if (!adapter) return { ...base, skipped: 'no-adapter' }
-  /* 다시 받기를 안 내는 원본이 있습니다 — 주기로 물어보는 쪽은 다음 주기가 곧 그것입니다. */
-  if (typeof adapter.fetchSince !== 'function') return { ...base, skipped: 'not-supported' }
-
-  const siteId = (inst.origin as any)?.siteId
-  const site: SiteDescriptor = siteId ? { siteId } : { siteId: instanceId }
-  const cursorKey = pushCursorKey(instanceId, scope)
-
-  /*
-   * `from` 을 주면 커서를 그 값으로 갈아 끼웁니다 — **저장된 커서를 건드리지 않습니다.** `fillSince`
-   * 가 나아간 만큼만 적으므로, 잃은 구간을 되찾은 뒤 커서는 원래 자리보다 앞서지 않습니다.
-   */
-  const cursor = from === undefined ? ((ref as any).liveCursor ?? {}) : withSeq((ref as any).liveCursor, cursorKey, from)
-  /* fillSince가 커서를 저장할 때 이 지역 값도 같이 바꾼다. 저장본을 다시 읽어 대사를 늦추지 않는다. */
-  let persistedCursor: unknown = cursor
-
-  const outcome = await fillSince({
-    cfg: ref.connectionConfig ?? {},
-    site,
-    scope,
-    cursorKey,
-    cursor,
-    fetch: (cfg, s, sc, since) => adapter.fetchSince!(cfg, s as SiteDescriptor, sc, since),
-    ingest: records => liveIngest(domainId, instanceId, records, 'fill'),
-    /*
-     * ── 넣기 전에 기억을 채운다 (2026-09-06) ──────────────────────────────────
-     * 중복 판정 기억은 프로세스 안에만 있다. 재기동하면 비워지고, 그러면 backfill 이 **이미 저널에
-     * 있는 사실도 다시 앉힌다.** 실측으로 39건이 통째로 다시 앉았다(저널 44 → 83).
-     *
-     * push 경로에서는 안 한다 — 거기서는 재전송이 창 안에 들어와 이미 걸리고, 봉투마다 저널을
-     * 조회하면 뜨거운 길이 느려진다.
-     */
-    beforeIngest: async records => {
-      const span = spanOf(records)
-      if (!span) return
-      const { identities, scanned, truncated } = await journalIdentities(domainId, instanceId, span)
-      const added = TwinEngine.warmDeduper(domainId, instanceId, identities)
-      if (truncated) {
-        twinWarn(
-          `[twin-fill] "${instanceId}" 의 저널을 ${scanned}줄까지만 읽었습니다 — 그보다 앞의 사실은 ` +
-            '다시 앉을 수 있습니다. 구간을 좁혀 부르거나 정체 색인이 필요합니다'
-        )
-      }
-      if (added) twinLog(`[twin-fill] "${instanceId}" — 저널에서 정체 ${added}개를 기억에 채웠습니다`)
-    },
-    saveCursor: async next => {
-      await repo.update({ id: (ref as any).id }, { liveCursor: next } as any)
-      persistedCursor = next
-    },
-    ...(maxPages ? { maxPages } : {})
-  })
-
-  /* 원본이 실제로 답한 범위가 있을 때만 기록한다. 범위를 모르는 것은 "정상"으로 덮지 않는다. */
-  await recordReferenceReconciliation({
-    domainId,
-    instanceId,
-    scope,
-    sourceRange: outcome.sourceRange,
-    cursorSeq: seqOf(persistedCursor, cursorKey),
-    firstSeqSeen: firstSeqOf(persistedCursor, cursorKey)
-  }).catch(err => twinWarn(`[twin-reconcile] "${instanceId}" · ${scope} 상태를 적지 못했습니다: ${err?.message ?? err}`))
-
-  const say = `[twin-fill] "${instanceId}" · ${scope} — ${outcome.applied}건 넣음 · ${outcome.pages}쪽 · ${outcome.stopped}${outcome.detail ? ` (${outcome.detail})` : ''}`
-  /* 끝난 것과 막힌 것을 다른 소리로 남깁니다 — 구멍은 사람이 원본을 봐야 합니다. */
-  if (outcome.stopped === 'done' || outcome.stopped === 'no-progress') twinLog(say)
-  else twinWarn(say)
-
-  return { ...base, ...outcome }
-}
-
-/**
- * **그 번호들이 무엇이었나** — 구멍을 만났을 때 사람이 묻는다.
- *
- * 커넥터는 「418 다음이 420」까지만 말한다. 그 419 가 무엇이었는지 알려면 원본에 물어야 하고,
- * 그 길이 없어서 사람이 아웃박스를 손으로 뒤졌다(2026-09-06).
- *
- * **판정하지 않는다.** 원본이 아는 것을 그대로 낸다 — 「그러니 포기해도 된다」는 되돌릴 수 없는
- * 판단이라 사람의 몫이다.
- */
-export async function seqReportOf(args: {
-  domainId: string
-  instanceId: string
-  scope: string
-  from: number
-  to: number
-}): Promise<{ instanceId: string; scope: string; report?: SeqReport; skipped?: 'unknown-twin' | 'no-source' | 'no-adapter' | 'not-supported' }> {
-  const { domainId, instanceId, scope, from, to } = args
-  const base = { instanceId, scope }
-
-  const inst = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })
-  if (!inst) return { ...base, skipped: 'unknown-twin' }
-  const ref = await getRepository(TwinReference).findOne({ where: { domain: { id: domainId }, source: instanceId } })
-  if (!ref) return { ...base, skipped: 'no-source' }
-  const adapter = getAdapter(ref.adapterType)
-  if (!adapter) return { ...base, skipped: 'no-adapter' }
-  /* 번호를 매기지 않는 원본은 물을 것이 없다 — 결함이 아니다. */
-  if (typeof adapter.seqReport !== 'function') return { ...base, skipped: 'not-supported' }
-
-  const siteId = (inst.origin as any)?.siteId
-  const site: SiteDescriptor | undefined = siteId ? { siteId } : undefined
-  return { ...base, report: await adapter.seqReport(ref.connectionConfig ?? {}, site, scope, from, to) }
-}

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

@@ -1,223 +0,0 @@
-/*
- * **놓친 구간을 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} 이어야 한다. 원본의 아웃박스에 구멍이 있다`
-}