@things-factory/headless-twin 10.0.17 → 10.0.19

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

@@ -42,11 +42,12 @@
  * 경계가 이미 거릅니다(§`FactDeduper`) — 이 파일이 따로 하지 않습니다. 응답에 몇 건이 중복이었는지
  * 함께 알립니다.
  */
-import { getRepository } from '@things-factory/shell'
+import { WEBHOOK_STATUS, checkSequence } from '@operato/ops-contract'
 
-import { TwinReference } from './twin-reference.js'
-import { getAdapter } from './reference-adapter.js'
-import { HOOK_STATUS, producedInstance, secretFromHeaders, secretMatches, type HookOutcome } from './hook-contract.js'
+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'
 
 /**
  * 훅 하나를 처리한다 — 찾고 · 확인하고 · 커넥터에게 옮기게 하고 · 유입으로 넘긴다.
@@ -60,16 +61,33 @@ export async function handleHook(args: {
   instanceId: string
   headers: Record<string, unknown>
   body: unknown
-  /** 레코드를 트윈에 넣는다 — 받은 수와 버린 수를 돌려준다. */
-  ingest: (instanceId: string, records: unknown[]) => { applied: number; duplicates: number; rejected: number }
+  /**
+   * 받은 바이트 그대로 — 서명을 확인하려면 이것이 있어야 한다.
+   *
+   * 파싱한 객체를 다시 문자열로 만들면 키 순서와 공백이 달라져 서명이 맞지 않는다. 없으면 서명을 쓰는
+   * 요청은 거절된다(§`authorizeHook`).
+   */
+  rawBody?: string
+  /** 서명 창을 재는 기준 시각. 부르는 쪽이 준다 — 여기서 읽으면 시험이 시계에 매인다. */
+  nowMs?: number
+  /** 레코드를 트윈에 넣는다 — 받은 수와 **떨어진 것들**을 돌려준다. */
+  ingest: (instanceId: string, records: unknown[]) => IngestResult
+  /**
+   * 저장소를 대신 쓰는 자리 — **시험이 재기동을 넣을 수 있게.**
+   *
+   * `ingest` 를 부르는 쪽이 넘겨 주는 것과 같은 이유다(위 §). 커서는 재기동을 넘어 살아야 하는데, 한
+   * 프로세스 안에서만 확인하면 「적히나」는 보이지만 「다시 세우면 읽히나」는 안 보인다. 그 둘이 갈린
+   * 결함을 이 저장소가 이미 겪었다.
+   */
+  store: HookStore
 }): Promise<HookOutcome> {
-  const { domainId, source, instanceId, headers, body, ingest } = args
+  const { domainId, source, instanceId, headers, body, rawBody, ingest } = args
+  const nowMs = args.nowMs ?? Date.now()
+  const { store } = args
 
-  const ref = await getRepository(TwinReference)
-    .findOne({ where: { domain: { id: domainId }, source } })
-    .catch(() => null)
+  const ref = await store.load(domainId, source)
   if (!ref) {
-    return { status: HOOK_STATUS.unknownTarget, body: { ok: false, error: `unknown connection "${source}"` } }
+    return { status: WEBHOOK_STATUS.unknownTarget, body: { ok: false, error: `unknown connection "${source}"` } }
   }
 
   const cfg: any = (ref as any).connectionConfig ?? {}
@@ -77,21 +95,22 @@ export async function handleHook(args: {
   if (!expected) {
     /* 비밀값을 선언하지 않은 연결은 훅을 받지 않는다 — 기본이 거부다. */
     return {
-      status: HOOK_STATUS.badSecret,
+      status: WEBHOOK_STATUS.badSecret,
       body: {
         ok: false,
         error: `connection "${source}" declares no hookSecret — set one in the connection settings before pushing to it`
       }
     }
   }
-  if (!secretMatches(secretFromHeaders(headers), expected)) {
-    return { status: HOOK_STATUS.badSecret, body: { ok: false, error: 'hook secret does not match' } }
+  const auth = authorizeHook({ headers, rawBody, secret: expected, nowMs })
+  if (auth.ok === false) {
+    return { status: WEBHOOK_STATUS.badSecret, body: { ok: false, error: auth.reason } }
   }
 
   const site = producedInstance(ref as any, instanceId)
   if (!site) {
     return {
-      status: HOOK_STATUS.unknownTarget,
+      status: WEBHOOK_STATUS.unknownTarget,
       body: { ok: false, error: `twin "${instanceId}" was not created by connection "${source}"` }
     }
   }
@@ -99,47 +118,245 @@ export async function handleHook(args: {
   const adapter: any = getAdapter(String((ref as any).adapterType ?? ''))
   if (typeof adapter?.handleInbound !== 'function') {
     return {
-      status: HOOK_STATUS.unsupported,
+      status: WEBHOOK_STATUS.unsupported,
       body: { ok: false, error: `connector "${(ref as any).adapterType}" cannot take pushed events (no handleInbound)` }
     }
   }
 
-  let records: unknown[]
+  let batch: InboundBatch
   try {
-    records = adapter.handleInbound(cfg, site, body, headers) ?? []
+    batch = adapter.handleInbound(cfg, site, body, headers)
   } catch (e: any) {
     /* 옮기지 못한 것은 그쪽 모양이 바뀐 것이다 — 다시 보내도 같으므로 재시도를 부르지 않는다. */
-    return { status: HOOK_STATUS.badPayload, body: { ok: false, error: e?.message ?? 'cannot translate the payload' } }
+    return { status: WEBHOOK_STATUS.badPayload, body: { ok: false, error: e?.message ?? 'cannot translate the payload' } }
   }
-  if (!Array.isArray(records)) {
-    return { status: HOOK_STATUS.badPayload, body: { ok: false, error: 'the connector did not return a list of records' } }
+  const items = batch?.items
+  if (!Array.isArray(items)) {
+    return {
+      status: WEBHOOK_STATUS.badPayload,
+      body: { ok: false, error: 'the connector did not return a list of items' }
+    }
   }
+
+  /*
+   * **번호 확인** — 이 자리가 프레임워크인 이유는 밀어 주는 모든 연결에 같은 규율이라야 하기 때문이다.
+   * 커넥터마다 만들면 한 곳이 빠지고, 빠진 그 연결에서만 사실이 없어진다.
+   *
+   * 번호를 매기지 않는 원본(chef · ppms)은 `seq` 를 주지 않고, 그때는 확인하지 않는다. 확인하지 않았다는
+   * 것은 응답에 남긴다 — 「확인했고 이상 없다」와 구별되어야 한다.
+   */
+  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 numbered = withSeqCount > 0 && scope !== undefined
+
+  /*
+   * **첫 구멍에서 멈춘다.** 구멍 뒤의 봉투를 받아들이면 그 구멍이 영영 메워지지 않는다 — 보내는 쪽은
+   * `expectedSeq` 부터 다시 보내고, 뒤엣것은 그때 함께 온다.
+   */
+  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 }
+  }
+
+  const records = items.slice(0, take).map(i => i.record)
+
   if (!records.length) {
-    /* 옮길 것이 없는 것은 오류가 아니다 — 그쪽이 우리와 무관한 것을 보낸 것일 수 있다. */
-    return { status: HOOK_STATUS.ok, body: { ok: true, offered: 0, applied: 0, duplicates: 0, rejected: 0 } }
+    /*
+     * 옮길 것이 없는 것은 오류가 아니다 — 그쪽이 우리와 무관한 것을 보낸 것일 수 있다. 다만 첫 봉투부터
+     * 구멍이면 그것은 받은 것이 없는 것이고, 그 앞부터 달라고 해야 한다.
+     */
+    if (gap) return gapOutcome(scope, gap)
+    if (advanced) await saveSeq(store, ref as any, advanced.scope, advanced.seq)
+    return {
+      status: WEBHOOK_STATUS.ok,
+      body: { ok: true, offered: 0, applied: 0, duplicates: 0, rejected: [], ...seqBody(scope, advanced, numbered) }
+    }
   }
 
-  let result: { applied: number; duplicates: number; rejected: number }
+  let result: IngestResult
   try {
     result = ingest(instanceId, records)
   } catch (e: any) {
-    return { status: HOOK_STATUS.failed, body: { ok: false, error: e?.message ?? 'ingest failed' } }
+    return { status: WEBHOOK_STATUS.failed, body: { ok: false, error: e?.message ?? 'ingest failed' } }
   }
+  const rejected = result.rejected ?? []
 
-  if (result.applied === 0 && result.duplicates === 0 && records.length > 0 && result.rejected === 0) {
+  if (result.applied === 0 && result.duplicates === 0 && rejected.length === 0) {
     /*
      * 넣었는데 한 건도 반영되지 않았고 중복도 거부도 아니면, 그 트윈이 실시간으로 돌지 않는 것이다.
-     * 200 을 주면 그쪽은 전달된 줄 알고 그 사실을 버린다. 그래서 재시도로 풀리지 않는다는 것을 코드로
-     * 말한다 — 사람이 트윈을 띄워야 한다.
+     * 200 을 주면 그쪽은 전달된 줄 알고 그 사실을 버린다.
+     *
+     * **커서를 올리지 않는다.** 한 건도 안 들어갔는데 번호를 올리면 그 번호는 다시 오지 않고, 트윈이
+     * 뜬 뒤에 그 구간이 비어 있게 된다.
      */
     return {
-      status: HOOK_STATUS.notLive,
-      body: { ok: false, error: `twin "${instanceId}" is not running live — nothing was applied`, offered: records.length }
+      status: WEBHOOK_STATUS.notLive,
+      body: {
+        ok: false,
+        error: `twin "${instanceId}" is not running live — nothing was applied`,
+        offered: records.length,
+        retryAfterMs: NOT_LIVE_RETRY_MS
+      }
+    }
+  }
+
+  if (advanced) await saveSeq(store, ref as any, advanced.scope, advanced.seq)
+
+  /*
+   * **구멍이 있으면 그것이 답을 정한다.** 앞의 것은 이미 들어갔으므로 `lastSeq` 까지는 보냄으로 표시하게
+   * 하고, 떨어진 것이 있으면 그것도 함께 싣는다 — 두 소식이 한 응답에 들어가야 보내는 쪽이 둘 다 한다.
+   */
+  if (gap) return gapOutcome(scope, gap, rejected, advanced)
+
+  if (rejected.length) {
+    /*
+     * **다시 보내라고 하지 않는다.** 떨어진 것은 모양이 틀린 것이라 같은 것을 다시 보내도 또 떨어지고,
+     * 함께 간 나머지는 이미 들어갔으므로 두 번 들어간다.
+     */
+    return {
+      status: WEBHOOK_STATUS.partial,
+      body: {
+        ok: false,
+        error: `${rejected.length} of ${records.length} records did not pass validation`,
+        offered: records.length,
+        applied: result.applied,
+        duplicates: result.duplicates,
+        rejected,
+        ...seqBody(scope, advanced, numbered)
+      }
     }
   }
 
   return {
-    status: HOOK_STATUS.ok,
-    body: { ok: true, offered: records.length, applied: result.applied, duplicates: result.duplicates, rejected: result.rejected }
+    status: WEBHOOK_STATUS.ok,
+    body: {
+      ok: true,
+      offered: records.length,
+      applied: result.applied,
+      duplicates: result.duplicates,
+      rejected: [],
+      ...seqBody(scope, advanced, numbered)
+    }
   }
 }
+
+/**
+ * 유입이 돌려주는 것.
+ *
+ * 떨어진 것을 **수가 아니라 목록으로** 받는다. 수만 받으면 보내는 쪽에 「몇 건이 떨어졌다」밖에 말할 수
+ * 없고, 그러면 무엇을 따로 두어야 할지 알 수 없어 배치 전체를 다시 보내거나 전부 버린다.
+ */
+export interface IngestResult {
+  applied: number
+  duplicates: number
+  rejected: { record: unknown; errors: string[] }[]
+}
+
+/**
+ * 구멍을 알리는 응답 — **앞의 것은 받았다는 것을 함께 말한다.**
+ *
+ * `lastSeq` 를 빼면 보내는 쪽은 이미 들어간 것까지 다시 보내고, 그것이 매번 중복으로 걸러지면서
+ * 처리량만 먹는다.
+ */
+function gapOutcome(
+  scope: string | undefined,
+  gap: { expectedSeq: number; lastSeq: number },
+  rejected: { record: unknown; errors: string[] }[] = [],
+  advanced?: { scope: string; seq: number }
+): HookOutcome {
+  return {
+    status: WEBHOOK_STATUS.sequenceGap,
+    body: {
+      ok: false,
+      error: 'sequence gap',
+      scope,
+      expectedSeq: gap.expectedSeq,
+      lastSeq: advanced?.seq ?? gap.lastSeq,
+      ...(rejected.length ? { rejected } : {})
+    }
+  }
+}
+
+/**
+ * 트윈이 안 돌 때 얼마나 쉬라고 할 것인가.
+ *
+ * 사람이 트윈을 띄워야 풀리므로 초 단위로 다시 두드릴 이유가 없다. 그렇다고 길게 잡으면 트윈이 뜬 뒤
+ * 그만큼 늦게 이어진다.
+ */
+const NOT_LIVE_RETRY_MS = 30_000
+
+/**
+ * 응답에 번호를 어떻게 적나 — **확인한 것과 확인하지 않은 것을 구별한다.**
+ *
+ * 번호를 매기지 않는 원본은 확인할 것이 없다. 그것을 응답에서 「이상 없다」와 같아 보이게 두면, 어느
+ * 연결이 연속성을 지키고 있는지 아무도 알 수 없다.
+ */
+function seqBody(
+  scope: string | undefined,
+  advanced: { scope: string; seq: number } | undefined,
+  numbered: boolean
+): Record<string, unknown> {
+  if (!numbered) return { sequenceChecked: false }
+  return { sequenceChecked: true, scope, lastSeq: advanced?.seq }
+}
+
+/**
+ * 커서에 번호를 적는다 — **반영한 뒤에만.**
+ *
+ * 넣기 전에 올리면, 넣다가 실패했을 때 그 번호는 다시 오지 않는다. 보내는 쪽은 200 을 못 받았으니 다시
+ * 보내겠지만, 그때는 커서가 이미 지나가 있어 `behind` 로 읽히고 버려진다.
+ *
+ * 적지 못하는 것은 사실 유입을 무르는 이유가 아니다 — 이미 들어간 사실은 그대로 두고, 다음 번호가 오면
+ * `gap` 으로 드러난다. 그래서 실패를 던지지 않고 남긴다.
+ */
+async function saveSeq(
+  store: HookStore,
+  ref: { id: string; liveCursor?: unknown },
+  scope: string,
+  seq: number
+): Promise<void> {
+  const next = withSeq(ref.liveCursor, scope, seq)
+  ref.liveCursor = next
+  await store
+    .saveCursor(ref.id, next)
+    .catch(err => twinWarn(`[twin-hook] 번호를 커서에 적지 못했다 (${scope}=${seq}) — ${err?.message ?? err}`))
+}
+
+/**
+ * 훅이 저장소에 닿는 두 자리 — 연결을 찾는 것과 커서를 적는 것.
+ *
+ * 이 둘만 밖으로 낸다. 나머지는 인자만 보고 답하므로 시험이 데이터베이스를 세우지 않아도 된다.
+ */
+export interface HookStore {
+  load(domainId: string, source: string): Promise<any | null>
+  saveCursor(refId: string, cursor: unknown): Promise<void>
+}
+

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

@@ -2,7 +2,8 @@ import { twinLog, twinWarn, twinError } from '../../engine/log.js'
 import { getRepository } from '@things-factory/shell'
 
 import { getAdapter, type ConnectionConfig, type LiveFeedContinuity, type ObservedItemFact, type SiteDescriptor } from './reference-adapter.js'
-import { TwinEngine, ingestCanonicalRecords, registerLiveFeedProbe, type CanonicalRecord } from '../../engine/index.js'
+import { TwinEngine, ingestCanonicalRecords, registerLiveFeedProbe } from '../../engine/index.js'
+import { type CanonicalRecord } from '@operato/ops-contract'
 import { TwinInstance } from '../twin-instance/twin-instance.js'
 import { TwinReference } from './twin-reference.js'
 
@@ -77,7 +78,12 @@ export async function startReferenceLiveFeed(
       return
     }
     const offered = Array.isArray(records) ? records.length : records ? 1 : 0
-    const { accepted, rejected, masterData } = ingestCanonicalRecords(records as CanonicalRecord[], domainId, new Date().toISOString())
+    const { accepted, rejected, masterData } = ingestCanonicalRecords(
+      records as CanonicalRecord[],
+      domainId,
+      new Date().toISOString(),
+      TwinEngine.factScope(domainId, instanceId)
+    )
     /*
      * ── **사건이 아닌 것은 상태만 세운다** (2026-08-28) ─────────────────────────
      *

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

@@ -7,7 +7,7 @@
  * 좌표·representations 는 트윈 공간층(보완/추가). 실 시스템이 좌표를 안 주면 layout 없이 위상만 인제스트.
  */
 
-import type { DomainSystem, EquipmentLevel, TestSpecificationCriterion, WorkCalendarEntry } from '@operato/twin-kernel'
+import type { DomainSystem, EquipmentLevel, TestSpecificationCriterion, WorkCalendarEntry } from '@operato/ops-contract'
 
 export interface RefLocation {
   id: string
@@ -150,7 +150,16 @@ export interface RefEquipment {
   homeLocationId: string
   mtbfMs?: number // 평균 고장 간격(확률적 고장) — 지정 시 커널이 breakdown 시뮬 → 주목(고장) 발생
   mttrMs?: number // 평균 수리 시간
-  gs1Id?: string // 정식 GS1 정체성(§J) — 설비=GIAI.
+  /**
+   * **이 설비의 전역 정체성** — 커널 선언의 `equipment[].identity` 로 그대로 간다.
+   *
+   * 예전 이름은 `gs1Id` 였다. 그런데 **GS1 키가 아닌 것이 정상이다** — 실측한 값은 인버터의
+   * 하드웨어 식별자(`ES100000007d8d061d-1`)이고, 원본이 GIAI 를 주면 그것도 여기 들어온다.
+   * 이름이 한 종류만 가리키면 다른 종류가 들어올 때 그 자리를 못 쓴다.
+   *
+   * 자리(`RefLocation.gs1Id`)는 그대로다 — 그쪽은 실제로 SGLN 이 온다.
+   */
+  identity?: string
   /**
    * 교대(가동시간) — 이 시간대에만 배정된다. `startHour <= endHour` 면 같은 날, 넘어가면 야간(22→6).
    * 미지정=24시간 가용. 교대 밖 자원은 고장·계획정지와 **구별되는 이유**로 쉰다(상태에 드러난다).
@@ -740,7 +749,7 @@ export function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTw
 
   const equipment = (master.equipment ?? []).map(e => ({
     id: e.id, kind: e.kind, ...(e.name ? { name: e.name } : {}), ...(e.description ? { description: e.description } : {}), ...(e.testResults?.length ? { testResults: e.testResults } : {}),
-    homeLocation: e.homeLocationId, mtbfMs: e.mtbfMs, mttrMs: e.mttrMs, gs1Id: e.gs1Id,
+    homeLocation: e.homeLocationId, mtbfMs: e.mtbfMs, mttrMs: e.mttrMs, ...(e.identity ? { identity: e.identity } : {}),
     ...(e.window ? { window: e.window } : {}),
     /* 속성은 손대지 않고 통과 — 이동시간 추정기가 kind 별 속도를 여기서 읽는다(단위 코드 그대로). */
     ...(e.properties?.length ? { properties: e.properties } : {}), ...(e.workCalendar?.length ? { workCalendar: e.workCalendar } : {}), ...(e.testSpecificationIds?.length ? { testSpecificationIds: e.testSpecificationIds } : {}),

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

@@ -7,7 +7,7 @@ import { ScalarObject, getRepository } from '@things-factory/shell'
 
 import { TwinEngine } from '../../engine/index.js'
 import { readRestartPolicy } from '../../engine/restart-policy.js'
-import { readBoardEquipment } from '@operato/twin-kernel'
+import { readBoardEquipment } from '@operato/ops-contract'
 
 import { applyKnobDefaults, filledKnobKeys } from './knob-defaults.js'
 import type { KnobDef } from './template-registry.js'

package/server/service/reference/template-registry.ts

@@ -4,7 +4,7 @@
  * 둘 다 같은 인제스트 경로(ingestMaster)로 흐른다 — 원천이 고정이냐 합성이냐만 다르다(board-authoring §10).
  * 앱(operato-twin)이 bootstrap 에서 자기 아키타입을 registerTemplate 한다. 표현(map/image/model) 무관.
  */
-import type { DomainSystem } from '@operato/twin-kernel'
+import type { DomainSystem } from '@operato/ops-contract'
 
 import type { ReferenceMaster } from './reference-master.js'
 

package/server/service/twin-backfill/backfill-period-facts.ts

@@ -0,0 +1,168 @@
+import { getRepository } from '@things-factory/shell'
+
+import { TwinEvent } from '../twin-event/twin-event.js'
+import { TwinEngine } from '../../engine/twin-engine.js'
+import { ingestCanonicalRecords } from '../../engine/canonical-ingest.js'
+import { absoluteTime } from '../../engine/read-time.js'
+import { judgeBackfill, splitAlreadyThere } from './backfill-shape.js'
+
+/*
+ * 지난 기록 채우기 — **저널에만 쓴다. 트윈의 「지금」을 건드리지 않는다.**
+ *
+ * ── 왜 라이브 문으로 넣을 수 없나 (2026-08-30) ──────────────────────────────
+ * 커널의 상태는 「지금」이다. 늦게 온 옛 표본은 가드가 막는다(그렇게 만들었다). 지난 기록을 라이브
+ * 문으로 넣으면 둘 중 하나다 — 가드에 막히거나, 트윈의 시계가 과거로 끌린다. 둘 다 나쁘다.
+ *
+ * 그래서 이 길은 저널에만 쓴다. 상태는 그대로 두고, 저널을 읽는 쪽(성과 계산·이력 화면)만 그 사실을
+ * 보게 된다.
+ *
+ * ── 무엇을 받나 ────────────────────────────────────────────────────────────
+ * **마감된 구간 사실만** 받는다. 시점의 관측(계량 표본·설비 상태·발전 적산)은 받지 않는다 — 그것들은
+ * 커널의 상태를 바꾸는 사실이라, 상태를 건너뛰고 저널에만 넣으면 상태와 저널이 갈라진다.
+ *
+ * ── 같은 기간을 두 번 넣지 않는다 ──────────────────────────────────────────
+ * 마감된 구간 사실은 정체성이 내용에 있다(커널 0.7.81: 종류·대상·시작·끝). 그 id 로 이미 있는 것을
+ * 가려낸다. 저장소의 제약으로 막지 않는 이유는 드라이버가 다섯이고 충돌 처리가 제각각이기 때문이다 —
+ * 구간 단위로 한 번 읽어 가려내는 편이 이식성이 있고 값도 싸다(한 시간에 한 줄이면 하루 24줄이다).
+ *
+ * ── 보존보다 오래된 것은 받지 않는다 ───────────────────────────────────────
+ * 저널은 보존 기간이 지나면 지운다. 그보다 오래된 것을 채우면 다음 정리에서 지워진다. 조용히 넣고
+ * 지워지면 아무도 모르므로, **거절하고 이유를 말한다.**
+ */
+
+export interface BackfillResult {
+  /** 저널에 새로 적은 수. */
+  written: number
+  /** 이미 있어서 건너뛴 수 — 다시 읽어도 중복이 쌓이지 않는다는 뜻이다. */
+  skipped: number
+  /** 받지 않은 것과 그 이유. 조용히 버리지 않는다. */
+  refused: { record: unknown; reason: string }[]
+}
+
+/** 이 도메인의 보존 기간(일). 정책이 없으면 `undefined` — 그때는 오래됨을 판정하지 않는다. */
+async function retentionDaysOf(domainId: string): Promise<number | undefined> {
+  const perDomain = TwinEngine.retentionDaysOf ? await TwinEngine.retentionDaysOf(domainId).catch(() => undefined) : undefined
+  const days = perDomain ?? TwinEngine.JOURNAL_RETENTION_DAYS
+  return days && days > 0 ? days : undefined
+}
+
+/**
+ * 지난 기록을 저널에 채운다.
+ *
+ * `records` 는 라이브와 **같은 모양**이다 — 커넥터가 다른 어휘를 배울 필요가 없다. 검증·갈림·id 만들기는
+ * 커널의 유입이 그대로 한다(§`ingestCanonicalRecords`).
+ */
+export async function backfillPeriodFacts(input: {
+  domainId: string
+  instanceId: string
+  records: unknown[]
+  /** 이 시각을 「지금」으로 본다 — 보존 판정의 기준. 시험이 시각을 정할 수 있게 받는다. */
+  nowMs?: number
+}): Promise<BackfillResult> {
+  const { domainId, instanceId, records } = input
+  const nowMs = input.nowMs ?? Date.now()
+  const refused: { record: unknown; reason: string }[] = []
+
+  if (!Array.isArray(records) || !records.length) return { written: 0, skipped: 0, refused }
+
+  /* 검증과 갈림은 라이브와 같은 것을 쓴다 — 두 벌이 되면 채운 사실과 관측한 사실이 다른 규칙을 지난다. */
+  const { accepted, rejected } = ingestCanonicalRecords(
+    records as any,
+    domainId,
+    new Date(nowMs).toISOString(),
+    /* 어느 트윈의 사실인가 — 마감된 구간의 이름이 이것으로 갈린다(커널 §`SubjectBasis`). */
+    TwinEngine.factScope(domainId, instanceId)
+  )
+  for (const r of rejected) refused.push({ record: r.record, reason: (r.errors ?? []).join(' · ') })
+
+  const days = await retentionDaysOf(domainId)
+
+  const judged = judgeBackfill(accepted as any[], { nowMs, retentionDays: days })
+  refused.push(...judged.refused)
+  const keep = judged.keep
+
+  if (!keep.length) {
+    TwinEngine.recordIngestResult(
+      domainId,
+      instanceId,
+      records.length,
+      refused.map(r => ({ record: r.record, errors: [r.reason] })),
+      nowMs,
+      0
+    )
+    return { written: 0, skipped: 0, refused }
+  }
+
+  /*
+   * 이미 있는 것을 가려낸다 — 그 구간의 그 종류만 읽는다(색인이 받쳐 준다). 페이로드의 id 로 견주고,
+   * 저장소 제약에 기대지 않는다(드라이버 다섯).
+   */
+  const times = keep.map(e => absoluteTime(e.eventTime)!.getTime())
+  const fromAt = new Date(Math.min(...times))
+  const toAt = new Date(Math.max(...times))
+  const types = [...new Set(keep.map(e => String(e.eventType)))]
+
+  const existing = await getRepository(TwinEvent)
+    .createQueryBuilder('e')
+    .select(['e.payload AS "payload"'])
+    .where('e.domain = :domainId', { domainId })
+    .andWhere('e.instanceId = :instanceId', { instanceId })
+    .andWhere('e.eventType IN (:...types)', { types })
+    .andWhere('e.eventTime BETWEEN :fromAt AND :toAt', { fromAt, toAt })
+    .getRawMany<{ payload: unknown }>()
+
+  const seen = new Set<string>()
+  for (const row of existing) {
+    const p: any = typeof row.payload === 'string' ? safeParse(row.payload) : row.payload
+    const id = p?.eventId
+    if (typeof id === 'string' && id) seen.add(id)
+  }
+
+  const { fresh, skipped } = splitAlreadyThere(keep, seen)
+  if (!fresh.length) {
+    TwinEngine.recordIngestResult(
+      domainId,
+      instanceId,
+      records.length,
+      refused.map(r => ({ record: r.record, errors: [r.reason] })),
+      nowMs,
+      skipped
+    )
+    return { written: 0, skipped, refused }
+  }
+
+  /*
+   * 리비전은 **쓴 순서**다(일어난 순서가 아니다). 지난 사실이 지금 번호를 받는 것이 맞다 — 저널을
+   * 시각으로 읽는 쪽은 `eventTime` 을 보고, 리비전은 같은 시각을 가릴 때만 쓴다.
+   */
+  const start = TwinEngine.journalHead(domainId, instanceId)
+  const items = fresh.map((event, i) => ({ event, revision: start + i + 1 }))
+
+  await TwinEngine.persistCarried(domainId, instanceId, items)
+  TwinEngine.advanceJournalHead(domainId, instanceId, items.length)
+
+  /*
+   * 장부에 적는다 — **유입을 부르는 곳은 모두 적는다.** 한 경로만 빠지면 그 트윈의 유입 건강이
+   * 「모름」으로 보인다(§`ingest-health-wiring`).
+   *
+   * 건네받지 못한 수(`undelivered`)는 **거절한 것과 이미 있어서 건너뛴 것의 합**이다. 건너뛴 것은
+   * 버려진 것이 아니지만 이번에 새로 적히지도 않았다 — 「통과」로 세면 채운 양이 실제보다 커 보인다.
+   */
+  TwinEngine.recordIngestResult(
+    domainId,
+    instanceId,
+    records.length,
+    refused.map(r => ({ record: r.record, errors: [r.reason] })),
+    nowMs,
+    skipped
+  )
+  return { written: items.length, skipped, refused }
+}
+
+function safeParse(text: string): unknown {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}