@things-factory/headless-twin 10.0.18 → 10.1.0

package/server/service/reference/connection-portability.ts

@@ -0,0 +1,285 @@
+/*
+ * **연결을 내보내고 다시 들여옵니다** — 실제 셋업을 파일로 보관하고 되세웁니다.
+ *
+ * ── 이것은 데모가 아니라 제품 기능입니다 (2026-09-05) ───────────────────────
+ * 데모 시드(`seed-demo-twins.ts`)와 **다른 것**입니다. 그쪽은 내장 가상 마스터로 보여 줄 트윈을
+ * 만들고 `TWIN_PROVISION_DEMO` 뒤에 숨습니다. 이것은 **실제로 붙인 연결을 옮기는 길**이라
+ * 데모 스위치 뒤에 두지 않습니다 — 백업·이관·복구가 데모일 수 없습니다.
+ *
+ * 그래서 특정 공장을 제품 코드에 적지 않습니다. 적으면 배포마다 남의 공장이 하나씩 따라가고,
+ * 데모 시드 머리말이 적어 둔 「프로덕션 배포는 **트윈 0** 에서 시작한다」가 깨집니다. 무엇을 세울지는
+ * **파일이 말하고 코드는 그 파일을 읽을 줄만 압니다.**
+ *
+ * ── 왜 필요했나 ────────────────────────────────────────────────────────────
+ * 실 MES 두 공장을 트윈에 세웠는데(`mes-line-a` · `mes-miratek`) **그 셋업이 한 데이터베이스
+ * 안에만 있었습니다.** 잃으면 다시 손으로 만들어야 하고, 다른 배포에 옮길 길도 없었습니다.
+ *
+ * ── 담는 것과 안 담는 것 ────────────────────────────────────────────────────
+ *
+ *   담는다     연결 선언 — 주소 · 도메인 · 사이트 · 치수 · 이름공간 · 받는 자리
+ *   안 담는다   비밀값 — 토큰 · 웹훅 서명값 · 받는 쪽 비밀값
+ *   안 담는다   사실(저널) — 원본이 다시 보내면 된다. 담으면 **가짜 과거가 배포마다 복제된다**
+ *   안 담는다   마스터에서 온 트윈 모델 — 연결이 있으면 재동기화가 다시 만든다
+ *
+ * **비밀값은 이름만 적습니다.** 어느 칸이 채워져 있었는지는 알려 주되 값은 안 나갑니다 — 파일은
+ * 주고받는 물건이고, 한 번 나간 비밀값은 되돌릴 수 없습니다. 들여올 때 「이 셋이 없다」고 말하고
+ * 사람이 연결 화면에서 채웁니다.
+ *
+ * ── 왜 사실을 안 담나 ───────────────────────────────────────────────────────
+ * 저널은 되풀이 읽히고 미러로 복제되고 구독으로 방송됩니다. 내보낸 사실을 다른 배포에 들여오면
+ * **일어나지 않은 일이 그 공장의 지난 기록에 섭니다.** 커서만 옮겨 두면 원본이 그 뒤부터 다시
+ * 보내 주므로, 사실은 원본에서 오는 것이 맞습니다.
+ */
+
+/** 값이 아니라 **채워져 있었다는 사실**만 나가는 칸들. */
+export const SECRET_KEYS = ['token', 'hookSecret', 'intakeSecret', 'password', 'apiKey'] as const
+
+export interface PortableConnection {
+  source: string
+  system?: string
+  siteName?: string
+  adapterType: string
+  /** 비밀값을 뺀 연결 설정. */
+  config: Record<string, unknown>
+  /** 내보낼 때 채워져 있던 비밀 칸 이름 — 값은 없습니다. */
+  secretsRequired: string[]
+  /** 이 연결이 무엇을 세우나. */
+  scope?: unknown
+}
+
+export interface ConnectionBundle {
+  kind: 'operato-twin/connections'
+  version: 1
+  exportedAt: string
+  /** 어디서 내보냈나 — 사람이 나중에 「이게 어느 배포 것인가」를 물을 때 답합니다. */
+  exportedFrom?: { domain?: string; note?: string }
+  connections: PortableConnection[]
+}
+
+/**
+ * 무엇을 세우나 **선언만** 남깁니다 — 지난 동기화의 **측정값은 뺍니다.**
+ *
+ * `scopeSpec` 에는 `produced`(선언) 옆에 `assessments`(그때 몇 개가 섰나) · `lastFailures` 가 함께
+ * 삽니다. 그것까지 내보내면 새 배포가 **다른 기계에서 잰 수**를 자기 것으로 보입니다 — 「설비 42」가
+ * 아무것도 안 세운 배포의 화면에 서고, 그 수가 어디서 왔는지 아무도 모릅니다.
+ *
+ * 재는 것은 그 배포에서 다시 재야 합니다. 오늘 「설정을 고쳤다」와 「모델이 다시 섰다」를 가른 것과
+ * 같은 구별입니다.
+ */
+function producedOf(scopeSpec: any): { produced: unknown } | undefined {
+  const produced = scopeSpec?.produced
+  return Array.isArray(produced) && produced.length ? { produced } : undefined
+}
+
+const isSecret = (key: string): boolean =>
+  (SECRET_KEYS as readonly string[]).includes(key) || /secret|token|password|apikey/i.test(key)
+
+/**
+ * 연결 행들을 옮길 수 있는 모양으로 — **비밀값을 빼고**.
+ *
+ * 빼는 판정을 이름으로 합니다. 목록으로만 하면 커넥터가 새 비밀 칸을 더할 때 그 값이 조용히
+ * 파일로 나갑니다 — 이름 규칙을 함께 두어 **새 칸이 기본으로 안 나가게** 합니다.
+ */
+export function exportConnections(
+  rows: readonly { source: string; system?: string; siteName?: string; adapterType: string; connectionConfig?: any; scopeSpec?: any }[],
+  meta: { at: string; domain?: string; note?: string }
+): ConnectionBundle {
+  return {
+    kind: 'operato-twin/connections',
+    version: 1,
+    exportedAt: meta.at,
+    ...(meta.domain || meta.note ? { exportedFrom: { ...(meta.domain ? { domain: meta.domain } : {}), ...(meta.note ? { note: meta.note } : {}) } } : {}),
+    connections: rows.map(r => {
+      const cfg = (r.connectionConfig ?? {}) as Record<string, unknown>
+      const kept: Record<string, unknown> = {}
+      const secrets: string[] = []
+      for (const [k, v] of Object.entries(cfg)) {
+        if (isSecret(k)) {
+          /* 비어 있던 칸은 적지 않습니다 — 「채워야 한다」와 「이 커넥터에 그런 칸이 있다」는 다릅니다. */
+          if (String(v ?? '').trim()) secrets.push(k)
+          continue
+        }
+        kept[k] = v
+      }
+      return {
+        source: r.source,
+        ...(r.system ? { system: r.system } : {}),
+        ...(r.siteName ? { siteName: r.siteName } : {}),
+        adapterType: r.adapterType,
+        config: kept,
+        secretsRequired: secrets.sort(),
+        ...(producedOf(r.scopeSpec) ? { scope: producedOf(r.scopeSpec) } : {})
+      }
+    })
+  }
+}
+
+export type ImportAction =
+  | { action: 'create'; connection: PortableConnection; missingSecrets: string[] }
+  | { action: 'update'; connection: PortableConnection; missingSecrets: string[]; keptSecrets: string[] }
+  | { action: 'skip'; source: string; why: string }
+
+export interface ImportPlan {
+  actions: ImportAction[]
+  /** 사람이 연결 화면에서 채워야 하는 것 — 이것이 비어야 「시드만으로 끝」입니다. */
+  /**
+   * 사람이 환경에 넣어야 하는 비밀값.
+   *
+   * `env` 를 함께 냅니다 — **그 이름을 사람이 손으로 적기 때문**입니다. 화면이 이름을 따로 만들면
+   * 규칙이 두 곳에 살고, 갈리는 날 「넣었는데 안 읽힌다」가 됩니다. 실제로 났습니다(2026-09-06):
+   * 화면이 `TWIN_SECRET__MES-MIRATEK__HOOKSECRET` 을 알려 줬는데 서버가 읽는 이름은
+   * `TWIN_SECRET__MES_MIRATEK__HOOK_SECRET` 이었습니다. 하이픈과 낙타 경계 둘 다 달랐습니다.
+   *
+   * `keys` 와 순서가 같습니다 — `keys[i]` 의 이름이 `env[i]` 입니다.
+   */
+  needsHuman: { source: string; keys: string[]; env: string[] }[]
+  /** 들여온 **뒤에** 두 연결이 같은 곳에 조치를 내게 되나 — 있으면 들여오면 안 됩니다. */
+  collisions: { intake: string; sources: string[] }[]
+  errors: string[]
+}
+
+/**
+ * 들여오기 **계획**을 먼저 냅니다 — 쓰기 전에 무엇이 일어날지 사람이 봅니다.
+ *
+ * ── 이미 있는 연결을 덮지 않습니다 ──────────────────────────────────────────
+ * 같은 이름이 이미 있으면 **선언만 갱신하고 비밀값은 그대로 둡니다.** 사람이 화면에서 넣은 값을
+ * 파일이 지우면, 파일 하나 들여왔다가 도는 연결이 멈춥니다. 데모 시드도 같은 규율을 적어 두었습니다
+ * (「옆 설정을 지우지 않는다 — 시드는 자기가 아는 것만 채운다」).
+ *
+ * ── 없는 비밀값을 지어내지 않습니다 ─────────────────────────────────────────
+ * 빈 값으로 채워 두면 연결이 서고 **동기화할 때 처음 실패합니다.** 그때는 무엇이 없어서인지 화면에서
+ * 멉니다. 여기서 이름을 대고 멈추는 것이 낫습니다.
+ */
+export function planImport(
+  bundle: unknown,
+  existing: readonly { source: string; connectionConfig?: any }[],
+  /** 지금 환경이 줄 수 있는 비밀값 이름들 — 값은 안 받습니다(이 함수는 값을 만지지 않습니다). */
+  availableSecrets: (source: string, key: string) => boolean = () => false
+): ImportPlan {
+  const errors: string[] = []
+  const b = bundle as ConnectionBundle
+  if (!b || typeof b !== 'object') return { actions: [], needsHuman: [], collisions: [], errors: ['들여올 것이 객체가 아닙니다'] }
+  if (b.kind !== 'operato-twin/connections') {
+    return { actions: [], needsHuman: [], collisions: [], errors: [`이 파일은 연결 꾸러미가 아닙니다(kind: ${JSON.stringify((b as any).kind ?? null)})`] }
+  }
+  if (b.version !== 1) errors.push(`모르는 판입니다(version: ${JSON.stringify((b as any).version)}) — 읽을 수 있는 것만 읽습니다`)
+  if (!Array.isArray(b.connections)) return { actions: [], needsHuman: [], collisions: [], errors: [...errors, 'connections 가 목록이 아닙니다'] }
+
+  const have = new Map(existing.map(e => [e.source, e]))
+  const seen = new Set<string>()
+  const actions: ImportAction[] = []
+  const needsHuman: { source: string; keys: string[]; env: string[] }[] = []
+
+  for (const c of b.connections) {
+    const source = String(c?.source ?? '').trim()
+    if (!source) {
+      errors.push('이름 없는 연결이 있습니다 — 건너뜁니다')
+      continue
+    }
+    if (seen.has(source)) {
+      actions.push({ action: 'skip', source, why: '같은 이름이 파일에 두 번 있습니다' })
+      continue
+    }
+    seen.add(source)
+    if (!String(c?.adapterType ?? '').trim()) {
+      actions.push({ action: 'skip', source, why: '커넥터 종류가 없습니다 — 무엇으로 붙일지 모릅니다' })
+      continue
+    }
+
+    const cur = have.get(source)
+    const curCfg = (cur?.connectionConfig ?? {}) as Record<string, unknown>
+    const wanted = Array.isArray(c.secretsRequired) ? c.secretsRequired.map(String) : []
+    const kept = wanted.filter(k => String(curCfg[k] ?? '').trim())
+    const missing = wanted.filter(k => !kept.includes(k) && !availableSecrets(source, k))
+
+    if (missing.length) needsHuman.push({ source, keys: missing, env: missing.map(k => secretEnvName(source, k)) })
+    actions.push(
+      cur
+        ? { action: 'update', connection: c, missingSecrets: missing, keptSecrets: kept }
+        : { action: 'create', connection: c, missingSecrets: missing }
+    )
+  }
+
+  /*
+   * **들여온 뒤의 모습으로 봅니다.** 파일 안에서만 보면 「이미 있는 연결과 부딪히는 것」을 못
+   * 잡습니다 — 그게 실제로 더 쉽게 나는 쪽입니다(하나는 화면에서, 하나는 파일에서 생깁니다).
+   */
+  const after = [
+    ...existing
+      .filter(e => !seen.has(e.source))
+      .map(e => ({ source: e.source, config: (e.connectionConfig ?? {}) as Record<string, unknown> })),
+    ...actions
+      .filter((a): a is Extract<ImportAction, { connection: PortableConnection }> => a.action !== 'skip')
+      .map(a => ({ source: a.connection.source, config: a.connection.config }))
+  ]
+  return { actions, needsHuman, collisions: intakeCollisions(after), errors }
+}
+
+/** 사람이 읽는 한 줄 — 화면과 로그가 같은 문장을 쓰게. */
+export function sayPlan(plan: ImportPlan): string {
+  const n = (a: ImportAction['action']) => plan.actions.filter(x => x.action === a).length
+  const head = `연결 ${plan.actions.length}개 — 새로 ${n('create')} · 갱신 ${n('update')} · 건너뜀 ${n('skip')}`
+  /* 부딪힘을 먼저 말합니다 — 비밀값이 없는 것은 안 도는 것이고, 부딪히는 것은 **잘못 도는 것**입니다. */
+  if (plan.collisions.length) {
+    const who = plan.collisions.map(c => `${c.sources.join(' · ')} → ${c.intake}`).join(', ')
+    return `${head}. ⚠ **두 연결이 같은 곳에 조치를 냅니다** — ${who}. 다른 공장의 작업지시가 한 공장에 섭니다`
+  }
+  if (!plan.needsHuman.length) return `${head}. 비밀값은 다 있습니다`
+  const who = plan.needsHuman.map(h => `${h.source}(${h.keys.join(' · ')})`).join(', ')
+  return `${head}. **비밀값을 사람이 넣어야 합니다** — ${who}. 연결 화면에서 채우면 그때부터 돕니다`
+}
+
+/**
+ * 비밀값이 사는 **환경 변수 이름** — `mes-miratek` · `hookSecret` → `TWIN_SECRET__MES_MIRATEK__HOOK_SECRET`.
+ *
+ * 꾸러미에는 비밀 칸의 이름만 있고 값은 환경에서 옵니다. 그 이름을 **사람이 손으로 적으므로** 규칙이
+ * 흔들리면 「넣었는데 안 읽힌다」가 됩니다 — 오늘 종일 잡은 「양쪽 다 초록인데 안 간다」의 설정 쪽
+ * 판본입니다. 그래서 이 규칙을 한 곳에 두고 시험으로 못 박습니다.
+ *
+ * 낙타 이름의 경계를 밑줄로 가릅니다 — 안 그러면 `HOOKSECRET` 과 `HOOK_SECRET` 이 갈려 한쪽만 읽힙니다.
+ */
+export function secretEnvName(source: string, key: string): string {
+  const up = (x: string) =>
+    x
+      .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+      .replace(/[^A-Za-z0-9]+/g, '_')
+      .replace(/^_+|_+$/g, '')
+      .toUpperCase()
+  return `TWIN_SECRET__${up(source)}__${up(key)}`
+}
+
+/**
+ * **두 연결이 같은 곳에 조치를 내지 않나** — 같으면 다른 공장의 작업지시가 한 공장에 섭니다.
+ *
+ * ── 왜 이 검사가 생겼나 (2026-09-05) ────────────────────────────────────────
+ * `mes-miratek` 이 서면서 한 커넥터가 처음으로 **공장 둘**을 달았습니다. 조치가 나가는 주소는
+ * `intakeSiteId` 가 정하는데(`operato-plant.ts:389`), 그 값이 트윈의 사이트 이름을 **이깁니다** —
+ * 트윈에서는 `mes-line-a` 인데 MES 의 도메인은 `system` 이라 그 override 가 필요합니다.
+ *
+ * 그래서 **연결을 베껴 만들고 그 칸만 안 고치면** 두 트윈의 조치가 같은 공장으로 갑니다. 오류가
+ * 안 납니다 — 저쪽은 정상적인 작업지시로 받고 **실제로 만듭니다.**
+ *
+ * 게이트에 이미 「사이트를 모르면 보내지 않는다」가 있는데(`no-site`), 그 이유가 적혀 있는 문장이
+ * **「잘못된 공장이 실제로 만든다」** 입니다. 이것은 그 둘째 길입니다 — 사이트를 아는데 **틀린
+ * 사이트를 압니다.**
+ *
+ * 파일로 연결을 만들 수 있게 되면서 더 쉬워졌습니다: 꾸러미를 베껴 이름만 바꾸면 받는 자리가
+ * 그대로 따라옵니다.
+ */
+export function intakeCollisions(
+  connections: readonly { source: string; adapterType?: string; config?: Record<string, unknown> }[]
+): { intake: string; sources: string[] }[] {
+  const byIntake = new Map<string, string[]>()
+  for (const c of connections) {
+    const cfg = c.config ?? {}
+    /* 받는 자리를 정하는 규칙은 커넥터의 것과 같아야 합니다 — 여기서 다시 지으면 두 벌이 됩니다. */
+    const intake = String(cfg.intakeSiteId ?? cfg.siteId ?? '').trim()
+    /* 조치를 낼 수 없는 연결은 부딪힐 것이 없습니다 — 주소가 없으면 아무 데도 안 갑니다. */
+    if (!intake || !String(cfg.intakeEndpoint ?? '').trim()) continue
+    const key = `${String(cfg.intakeEndpoint).trim().replace(/\/$/, '')}::${intake}`
+    byIntake.set(key, [...(byIntake.get(key) ?? []), c.source])
+  }
+  return [...byIntake.entries()]
+    .filter(([, sources]) => sources.length > 1)
+    .map(([intake, sources]) => ({ intake, sources: sources.sort() }))
+}

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

@@ -0,0 +1,29 @@
+/*
+ * 빠진 구간을 **언제** 다시 받나 — 간격만 여기 둔다.
+ *
+ * ── 왜 따로인가 ─────────────────────────────────────────────────────────────
+ * `fill-loop.ts` 는 엔진과 TypeORM entity 를 물어서 테스트 프로세스가 적재할 수 없다. 값만 따로 두면
+ * 테스트가 가벼운 import 로 확인한다.
+ *
+ * 오늘 같은 자리를 세 번 밟았다(`reference-links` · `fill-dedupe` · 여기). 이 저장소에서 **판정과
+ * 값은 배선과 나누는 것이 규율**이다 — 나누면 테스트가 붙고, 안 나누면 안 붙는다.
+ */
+
+/**
+ * 그물의 간격 — **10분. 30초가 아니다.**
+ *
+ * 인티그레이션 레인이 측정으로 준 권고다. backfill 은 원본에 조회를 걸고 저널을 읽는다. 30초마다
+ * 돌면 얻는 것 없이 두 쪽을 계속 친다 — 놓친 구간은 10분 뒤에 받아도 사실이 달라지지 않는다.
+ *
+ * 규칙 주기(`RULE_PERIOD_MS`, 30초)에 얹지 않는 이유이기도 하다. 얹으면 간격이 그쪽에 묶이고,
+ * 나중에 규칙 주기를 바꾸면 이쪽이 소리 없이 따라간다.
+ */
+export const FILL_PERIOD_MS = 10 * 60_000
+
+/**
+ * 같은 단위를 이 간격 안에 두 번 부르지 않는다.
+ *
+ * 구멍을 본 자리에서 부르는 길이 뜨거운 길이다. 밀어 받는 쪽이 구멍 뒤의 봉투를 계속 보내면 그때마다
+ * 구멍 판정이 나고, 막지 않으면 **봉투마다 backfill 이 돈다.**
+ */
+export const FILL_DEBOUNCE_MS = 60_000

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

@@ -0,0 +1,66 @@
+/*
+ * **backfill 이 이미 있는 사실을 다시 앉히지 않게 한다** — 저널에서 정체를 읽어 기억을 채운다.
+ *
+ * ── 무엇이 있었나 (2026-09-06 측정) ─────────────────────────────────────────
+ * 중복 판정 기억(`FactDeduper`)은 **프로세스 안에만 있다.** 재기동하면 비워지고, 그 뒤 backfill 을
+ * 돌리면 이미 저널에 있는 사실도 「처음 본 것」이 된다.
+ *
+ * ```
+ * mes-line-a 를 재기동 뒤 backfill
+ *   저널 44 → 83건 · 서로 다른 것 39가지 · 중복 44가지
+ *   같은 프로세스에서 다시 돌리면 applied 0 (기억이 살아 있어서)
+ * ```
+ *
+ * push 경로에서는 안 보인다. 재전송이 몇 분 안에 오므로 창(20,000) 안에서 걸린다.
+ * **backfill 이 그 전제를 깬다** — 몇 달 전 사실을 지금 받으니 재기동 한 번이면 그 구간이 통째로
+ * 다시 앉는다.
+ *
+ * ── 왜 여기서만 하나 ────────────────────────────────────────────────────────
+ * push 경로는 뜨거운 길이다. 봉투마다 저널을 조회하면 그 길이 느려지고, 거기서는 재전송이 창 안에
+ * 들어와 이미 걸린다.
+ *
+ * backfill 은 자주 돌지 않고 한 번에 많이 받는다. 그래서 **한 번의 조회로 그 구간을 통째로** 읽어
+ * 기억을 채운다 — 레코드마다 묻지 않는다.
+ *
+ * ── 근본 고침은 따로 있다 ───────────────────────────────────────────────────
+ * 저널에 정체 칸과 unique index 를 두는 것이 근본이다. 그런데 저널이 2,484,472행이고, 개발 중에
+ * 그 표에 칸을 더하면 sqlite 가 표를 통째로 다시 쓴다. postgres 첫 부팅 직전에 한 번에 하기로 적어
+ * 두었다(`design/plans/postgres-column-types.md`).
+ */
+import { Between } from 'typeorm'
+
+import { getRepository } from '@things-factory/shell'
+
+import { TwinEvent } from '../twin-event/twin-event.js'
+import { factIdentity } from '../../engine/ingest-dedupe.js'
+
+/** 구간 판정은 가벼운 파일에 있다 — 부르는 쪽이 한 곳에서 가져가게 다시 내보낸다. */
+export { spanOf } from './fill-span.js'
+
+/** 한 번에 읽을 저널 줄의 상한 — 넘으면 읽은 만큼만 채우고 그 사실을 말한다. */
+const SCAN_MAX = 50_000
+
+/**
+ * 그 구간의 저널을 읽어 **정체 목록**을 만든다.
+ *
+ * 저장된 payload 가 봉투 그대로라(`eventId` · `eventType` · `eventTime` · `data`) 유입 때와 같은
+ * 함수로 정체를 만든다. 여기서 따로 만들면 두 곳이 다른 규칙을 갖고, 어긋나는 날 조용히 다시 앉는다.
+ */
+export async function journalIdentities(
+  domainId: string,
+  instanceId: string,
+  span: { from: Date; to: Date }
+): Promise<{ identities: string[]; scanned: number; truncated: boolean }> {
+  const rows = await getRepository(TwinEvent).find({
+    where: { domain: { id: domainId } as any, instanceId, eventTime: Between(span.from, span.to) as any },
+    select: { id: true, payload: true } as any,
+    take: SCAN_MAX
+  })
+
+  const identities: string[] = []
+  for (const r of rows as any[]) {
+    const id = factIdentity(r?.payload)
+    if (id) identities.push(id)
+  }
+  return { identities, scanned: rows.length, truncated: rows.length >= SCAN_MAX }
+}

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

@@ -0,0 +1,153 @@
+/*
+ * **빠진 구간을 언제 다시 받나** — 세 자리에서 부른다.
+ *
+ * ── 왜 세 자리인가 (인티그레이션 레인의 측정 권고, 2026-09-05) ──────────────
+ * ```
+ * 1  재기동 직후 한 번    우리가 내려가 있는 동안 그쪽이 보낸 것을 못 받았다
+ * 2  구멍을 본 그 자리     번호가 비었다는 것을 아는 순간이 가장 이르다
+ * 3  10분 그물            위 둘이 다 놓치는 경우 — 그쪽이 아예 안 보낸 구간
+ * ```
+ *
+ * **30초가 아니다.** 그 권고에 근거가 있었다 — backfill 은 원본에 조회를 걸고 저널을 읽는다.
+ * 30초마다 돌면 얻는 것 없이 두 쪽을 계속 친다. 놓친 구간은 10분 뒤에 받아도 사실이 달라지지 않는다.
+ *
+ * 규칙 주기(`rule-loop.ts`, 30초)에 얹지 않는 이유가 그것이다. 얹으면 간격이 그쪽에 묶이고, 나중에
+ * 규칙 주기를 바꾸면 이쪽이 소리 없이 따라간다.
+ *
+ * ── 겹쳐 돌지 않는다 ────────────────────────────────────────────────────────
+ * 한 바퀴가 간격보다 오래 걸리면 다음 발화가 겹친다. 겹치면 두 바퀴가 같은 구간을 받고, 그 순간
+ * 중복 판정이 두 벌의 기억을 갖는다.
+ *
+ * ── 도는 트윈만 본다 ────────────────────────────────────────────────────────
+ * 멈춘 트윈에는 사실을 넣을 커널이 없다. `runFill` 이 그것을 다시 확인하지만 여기서 미리 걸러
+ * 헛조회를 안 만든다.
+ */
+import { twinError, twinLog, twinWarn } from '../../engine/log.js'
+import { TwinEngine } from '../../engine/twin-engine.js'
+
+import { runFill, type FillRunResult } from './reference-fill-run.js'
+
+/* 간격은 가벼운 파일에 있다 — 테스트가 붙게(§`fill-cadence.ts`). 부르는 쪽이 한 곳에서 가져가게 다시 내보낸다. */
+export { FILL_DEBOUNCE_MS, FILL_PERIOD_MS } from './fill-cadence.js'
+import { FILL_DEBOUNCE_MS, FILL_PERIOD_MS } from './fill-cadence.js'
+
+/** 어느 단위를 언제 마지막으로 받았나 — `domainId::instanceId::scope`. */
+const lastRun = new Map<string, number>()
+
+let timer: any
+let running = false
+
+function recently(key: string, now: number): boolean {
+  const last = lastRun.get(key)
+  return last !== undefined && now - last < FILL_DEBOUNCE_MS
+}
+
+/**
+ * 그 단위를 한 번 받는다 — **커서부터 이어서.**
+ *
+ * `from` 을 주지 않는다. 밑에서부터 다시 받는 것은 사람이 정하는 일이고(`fillTwinScope(from:)`),
+ * 주기가 스스로 할 일이 아니다 — 그것을 주기로 돌리면 매번 원본의 전 구간을 훑는다.
+ */
+export async function fillOnce(domainId: string, instanceId: string, scope: string): Promise<FillRunResult | undefined> {
+  const key = `${domainId}::${instanceId}::${scope}`
+  const now = Date.now()
+  if (recently(key, now)) return undefined
+  lastRun.set(key, now)
+
+  const out = await runFill({ domainId, instanceId, scope })
+  /*
+   * 받은 것이 있을 때만 말한다. 「받을 것이 없었다」를 10분마다 적으면 로그가 그 줄로 차고, 그러면
+   * 진짜 받은 날을 못 본다.
+   */
+  if (out.applied) twinLog(`[twin-fill] "${instanceId}" · ${scope} — 빠진 구간에서 ${out.applied}건을 받았습니다`)
+  return out
+}
+
+/**
+ * **구멍을 본 자리에서 부른다** — 기다리지 않는다.
+ *
+ * 훅의 응답이 이것 때문에 늦으면 보내는 쪽이 되풀이하고, 그러면 같은 봉투가 두 번 온다. 조치를
+ * 잇는 자리(`settleEffects`)와 같은 규율이다.
+ */
+export function requestFill(domainId: string, instanceId: string, scope: string): void {
+  void fillOnce(domainId, instanceId, scope).catch(err =>
+    twinWarn(`[twin-fill] "${instanceId}" · ${scope} 를 받지 못했습니다 — ${err?.message ?? err}`)
+  )
+}
+
+/**
+ * 도는 트윈을 한 바퀴 돈다.
+ *
+ * **어느 단위를 받을지는 커서가 말한다.** 커서에 적힌 흐름이 그동안 받아 온 것들이고, 그것이
+ * 없으면 아직 아무것도 안 받은 연결이라 받을 구간도 없다.
+ */
+export async function fillAllOnce(): Promise<{ tried: number; applied: number }> {
+  let tried = 0
+  let applied = 0
+  for (const { domainId, instanceId } of TwinEngine.ownedTwins()) {
+    for (const scope of await scopesOf(domainId, instanceId)) {
+      tried++
+      const out = await fillOnce(domainId, instanceId, scope)
+      applied += out?.applied ?? 0
+    }
+  }
+  return { tried, applied }
+}
+
+/**
+ * 그 연결이 받아 온 단위들 — **커서에 적힌 것.**
+ *
+ * 커서 열쇠는 `instanceId::scope` 다(§`pushCursorKey`). 여기서 그 규칙을 다시 적지 않고 앞부분을
+ * 떼어 낸다 — 두 곳이 같은 규칙을 가지면 어긋나는 날 이 주기가 엉뚱한 단위를 받는다.
+ */
+async function scopesOf(domainId: string, instanceId: string): Promise<string[]> {
+  const { getRepository } = await import('@things-factory/shell')
+  const { TwinReference } = await import('./twin-reference.js')
+  const ref = await getRepository(TwinReference).findOne({ where: { domain: { id: domainId }, source: instanceId } })
+  const streams = (ref as any)?.liveCursor?.streams
+  if (!streams || typeof streams !== 'object') return []
+
+  const prefix = `${instanceId}::`
+  return Object.keys(streams)
+    .filter(k => k.startsWith(prefix))
+    .map(k => k.slice(prefix.length))
+    .filter(s => s)
+}
+
+/**
+ * 주기를 세운다 — 두 번 불러도 하나만 선다.
+ *
+ * **기동에서 한 번 먼저 돈다**(§1). 우리가 내려가 있는 동안 그쪽이 보낸 것을 그때 받는다. 첫 바퀴를
+ * 10분 뒤로 미루면 그 10분 동안 화면이 빈 구간을 그대로 보인다.
+ */
+export function startFillLoop(periodMs = FILL_PERIOD_MS): void {
+  if (timer) return
+
+  const turn = () => {
+    if (running) return
+    running = true
+    fillAllOnce()
+      .then(({ tried, applied }) => {
+        if (applied) twinLog(`[twin-fill] 한 바퀴 — ${tried}개 단위에서 ${applied}건을 받았습니다`)
+      })
+      .catch(err => twinError(`[twin-fill] 주기가 실패했습니다 — ${err?.message ?? err}`))
+      .finally(() => {
+        running = false
+      })
+  }
+
+  timer = setInterval(turn, periodMs)
+  /*
+   * 기동 직후 한 번. 조금 늦춰서 돈다 — 커널이 되살아나기 전에 부르면 도는 트윈이 0개라 아무것도
+   * 안 받고, 그러면 그 한 번이 없는 것과 같다.
+   */
+  setTimeout(turn, 15_000).unref?.()
+}
+
+/** 주기를 내린다 — 테스트가 재기동을 넣을 수 있게. */
+export function stopFillLoop(): void {
+  if (timer) clearInterval(timer)
+  timer = undefined
+  running = false
+  lastRun.clear()
+}

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

@@ -0,0 +1,31 @@
+/*
+ * backfill 이 읽을 저널 구간을 정하는 판정.
+ *
+ * 조회 코드(`fill-dedupe.ts`)와 나눠 둔다 — 그쪽은 TypeORM entity 를 물어서 테스트 프로세스가
+ * 적재할 수 없다. 판정만 따로 두면 테스트가 가벼운 import 로 확인할 수 있다.
+ */
+import { factEventTime } from '../../engine/event-time.js'
+
+/**
+ * 이 레코드들이 덮는 시각 구간 — 하나도 시각을 말하지 않으면 `undefined`.
+ *
+ * **구간을 못 정하면 채우지 않는다.** 저널 전체를 읽는 쪽으로 넓히지 않는다 — 그것이 필요한
+ * 상황이면 조회가 아니라 unique index 로 풀어야 한다.
+ */
+export function spanOf(records: readonly unknown[]): { from: Date; to: Date } | undefined {
+  let lo = Number.POSITIVE_INFINITY
+  let hi = Number.NEGATIVE_INFINITY
+  for (const r of records) {
+    const t = Date.parse(String(factEventTime(r) ?? ''))
+    if (!Number.isFinite(t)) continue
+    if (t < lo) lo = t
+    if (t > hi) hi = t
+  }
+  if (!Number.isFinite(lo)) return undefined
+  /*
+   * 양쪽을 1초씩 넓힌다. 저장된 시각은 밀리초까지 있고 경계에서 같은 값이 부동소수로 갈릴 수 있다 —
+   * 넓게 읽는 것은 기억이 조금 더 차는 것뿐이라 손해가 없고, 좁게 읽으면 그 사실이 다시 앉는다.
+   */
+  return { from: new Date(lo - 1000), to: new Date(hi + 1000) }
+}
+