@things-factory/headless-twin 10.0.19 → 10.1.0

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

@@ -2,6 +2,12 @@ import type { ApprovedCommand } from '@operato/ops-contract'
 
 import type { ReferenceStep } from './reference-progress.js'
 import type { ReferenceMaster } from './reference-master.js'
+/*
+ * `fetchLinks` 가 돌려주는 관계 그룹. 정의는 이것을 소비하는 쪽에 하나만 둔다
+ * (`external-resolver.ts`). 여기서 같은 모양을 다시 선언하면 한쪽만 수정되는 날이 온다.
+ */
+import type { ExternalIncoming as ReferenceLinkGroup } from '../twin-model/external-resolver.js'
+export type { ReferenceLinkGroup }
 import { twinWarn } from '../../engine/log.js'
 
 /*
@@ -95,7 +101,37 @@ export interface AdapterMeta {
  *  · `live`    — 돌아가는 피드를 낸다(`openLiveFeed`).
  *  · `control` — 구동을 받는다(`control`) — 자극·속도·정지·초기화.
  */
-export type ReferenceCapability = 'live' | 'control'
+/**
+ * 이 원본에 무엇을 요구할 수 있나.
+ *
+ *  · `live`     — 관측을 이어서 낸다
+ *  · `control`  — 시뮬레이터를 움직인다(자극·배속·정지). 실 시스템은 갖지 않는다
+ *  · `actuate`  — **승인된 조치를 받는다.** 현장에 작업지시가 나가는 유일한 축이다
+ *
+ * ── `actuate` 를 늦게 넣은 이유 (2026-09-02) ────────────────────────────────
+ * 어댑터에 `actuate` 구현은 있었는데 이 축에 그 이름이 없었다. 그래서 셋이 동시에 조용했다.
+ *
+ *   화면    「이 원본이 지시를 받나」를 물을 수 없다 — 능력 목록에 그 이름이 없다
+ *   등록    구현했는데 선언 안 한 것을 알려 주지 않는다 — 검사 목록에 그 이름이 없다
+ *   넘김    리졸버가 어댑터를 찾지도 않고 무조건 거절했다 — 커넥터는 이미 만들어져 있었다
+ *
+ * 실제로 MES 커넥터가 `actuate` 를 다 만들어 두었는데, 넘기면 「구현이 없습니다」라고 답했다.
+ * 자리는 있고 길이 없는 상태였고, 이 저장소에서 가장 자주 나는 결함 부류다.
+ */
+/**
+ * 커넥터가 선언하는 능력.
+ *
+ * `idempotent-actuation` 은 다른 셋과 성질이 다르다 — 무엇을 할 수 있나가 아니라 **두 번 해도
+ * 같은가**다. 일꾼이 실패한 조치를 다시 넘길지 정할 때 이것만 본다(§`retryDecisionOf`).
+ *
+ * 선언하지 않으면 **거짓으로 읽는다.** 이 한 자리에서만 「모르면 안전한 쪽」이 거짓이고, 그
+ * 안전한 쪽이 「재시도하지 않음」이다 — 참으로 가정하면 현장에 지시가 두 건 선다.
+ *
+ * 선언에는 근거가 있어야 한다. operato-plant 는 MES 가 `correlationId` 로 기존 행을 찾아 같은
+ * 이름을 돌려주기 때문에 참이다 — 우리가 조심해서가 아니라 저쪽 동작이 그래서다. 저쪽이 그것을
+ * 바꾸면 이 선언이 거짓이 된다.
+ */
+export type ReferenceCapability = 'live' | 'control' | 'actuate' | 'idempotent-actuation'
 
 /** 원본에 보내는 구동 명령 — **시뮬레이터를 움직이는 말**이지 트윈을 고치는 말이 아니다. */
 export interface ControlCommand {
@@ -173,8 +209,30 @@ export interface ObservedItemFact {
  *
  * **`scope` 가 없으면 `seq` 도 없는 것으로 다룬다.** 번호만 있고 그 번호가 어느 줄의 것인지 모르면
  * 커서를 무엇으로 잡을지 짐작해야 하고, 짐작한 열쇠는 보내는 쪽이 줄을 하나 더 늘리는 날 어긋난다.
- * 실제로 operato-mes 가 `[domain, channel]` 마다 번호를 매기면서 봉투에 `channel` 을 싣지 않고 있었다.
+ * 실제로 operato-plant 가 `[domain, channel]` 마다 번호를 매기면서 봉투에 `channel` 을 싣지 않고 있었다.
  */
+/** 번호 하나에 대해 원본이 아는 것. */
+export interface SeqEntry {
+  seq: number
+  /**
+   * `unknown` 은 결함이 아니다 — 채번을 따로 들지 않는 원본은 「행이 없다」에서 잃은 것과 아직 안
+   * 간 것을 가를 수 없다. 그것을 `lost` 로 단정하면 사람이 없는 사실을 찾으러 간다.
+   */
+  state: 'present' | 'lost' | 'unissued' | 'unknown'
+  /** 그 봉투의 발생 시각 — `present` 일 때만. 무엇이었는지 사람이 알아보는 데 쓴다. */
+  at?: string
+  /** 그 봉투 자체 — `present` 이고 원본이 낼 수 있을 때만. 없어도 `state` 는 참이다. */
+  record?: unknown
+}
+
+/** 번호 구간에 대해 원본이 아는 것 — **원본이 아는 것만 낸다. 판정은 사람이 한다.** */
+export interface SeqReport {
+  scope: string
+  entries: SeqEntry[]
+  /** 상한에 닿아 구간을 다 못 냈다 — 알리지 않고 자르지 않는다. */
+  truncated?: boolean
+}
+
 export interface InboundBatch {
   /**
    * 옮긴 것들. 우리와 무관한 본문이면 빈 배열이다.
@@ -190,17 +248,66 @@ export interface InboundBatch {
    * 하나로 말할 수 없다.
    */
   scope?: string
+  /**
+   * (선택) **원본이 지금 가진 번호의 범위** — 우리 커서와 견주려면 이것이 있어야 한다.
+   *
+   * ── 왜 어댑터가 주나 (인티그레이션 레인 제안, 2026-09-06) ──────────────────
+   * 「가장 낮은 번호」를 묻는 방법이 원본마다 다르다. operato-plant 는
+   * `mesOutboxEvents(since: 0, limit: 1)` 이고, ppms·chef 는 아웃박스가 없어 번호 범위 자체가
+   * 없다. 프레임워크가 이것을 알 방법이 없다.
+   *
+   * ── 모르면 주지 않는다 ────────────────────────────────────────────────────
+   * **0 이나 추측을 넣지 않는다.** 0 을 넣으면 「원본이 1번부터 다 갖고 있다」로 읽히고, 그것이
+   * 거짓이면 「우리가 다 받았다」는 잘못된 결론이 나온다.
+   *
+   * `last` 에는 조건이 하나 붙는다. 쪽 상한에서 멈췄으면 그때의 번호는 **원본의 끝이 아니라
+   * 「여기까지 읽었다」**이므로 주지 않는다 — 주면 「원본에 더 없다」로 읽히는데 실제로는 더 있다.
+   */
+  sourceRange?: { first?: number; last?: number }
 }
 
 export interface InboundItem {
   /** 우리 어휘로 옮긴 레코드 하나. */
   record: unknown
+  /**
+   * 원본이 이 봉투에 붙인 id — **떨어졌을 때 그쪽이 자기 행을 찾는 열쇠다.**
+   *
+   * ── 왜 필요한가 (2026-09-07 측정) ──────────────────────────────────────────
+   * 훅 응답의 떨어진 목록이 `{ record, errors }` 였고, plant 은 그것을 **봉투 id 문자열 목록**으로
+   * 읽고 있었다. `Array.isArray` 는 통과하니 그쪽 guard 도 안 걸렸다 — id 를 맞추는데 객체라 하나도
+   * 안 맞고 **묶음 전체가 「보냈음」으로 찍혔다.** 422 와 `ok: false` 를 보냈는데도 그쪽 행은 재시도
+   * 0 · 오류 없음이었다.
+   *
+   * 이 값을 주면 응답이 `{ eventId, errors }` 로 나가고 그쪽이 그 행만 표시할 수 있다. 안 주면
+   * 레코드가 그대로 실려 나간다 — 무엇이 떨어졌는지 알 길이 그것뿐이고, 빈 id 를 실으면 보내는 쪽이
+   * 아무 행도 못 찾으면서 「알았다」고 여긴다.
+   */
+  eventId?: string
   /**
    * 이 봉투의 번호.
    *
    * **한 배치 안에서 있거나 없거나 하나로 통일한다.** 섞이면 빠진 것이 있는지 판단할 근거가 없다.
    */
   seq?: number
+  /**
+   * 이 봉투가 말하는 **발생 시각** — 레코드가 자기 시각을 안 말할 때 쓴다.
+   *
+   * ── 왜 필요한가 (2026-09-06 측정) ─────────────────────────────────────────
+   * 시각을 안 싣는 레코드는 `defaultEventTime`(= ingest 시각)으로 떨어진다. 그 값이 **실행할 때마다
+   * 다르다.** 그런데 fact identity 가 시각을 포함하므로, 같은 사실을 다시 받으면 dedupe 가 안 되고
+   * 새 사실로 앉는다.
+   *
+   * 실제로 그렇게 됐다. `fillTwinScope(from: 0)` 을 두 번 돌렸더니 mes-line-a 저널이
+   * 40 → 69건이 되고 중복이 27가지 생겼다. 시각을 말하는 레코드 12건만 되풀이로 걸러졌다.
+   *
+   * ── 봉투는 그 시각을 알고 있었다 ──────────────────────────────────────────
+   * plant 아웃박스가 `eventTime` 을 실어 보낸다. 그것이 갈 자리가 없어서 버려지고 있었다 —
+   * connector 주석이 그 위험을 적어 두고 자리를 요청해 두었다(`operato-plant.ts`).
+   *
+   * **레코드가 자기 시각을 말하면 그것이 이긴다.** 봉투의 시각은 「그 사실을 언제 보냈나」에 가깝고,
+   * 레코드의 시각은 「언제 일어났나」다. 둘이 다르면 뒤엣것이 맞다.
+   */
+  at?: string
 }
 
 /**
@@ -209,6 +316,30 @@ export interface InboundItem {
  * 흐름 열쇠는 **어댑터가 정한다**(`Record`). 계약이 이름을 닫으면 새 원본마다 계약을 고치게 된다.
  */
 export interface LiveFeedContinuity {
+  /**
+   * The name to take a task lease under, so only one instance polls this feed.
+   *
+   * ── Why this layer composes it ────────────────────────────────────────────
+   * `TaskLease` has no domain column on purpose: what is made exclusive is a
+   * loop, not a tenant's slice of one, and a task that does need to be
+   * per-tenant puts the tenant in the name so the unique index keeps meaning
+   * what it says.
+   *
+   * An adapter cannot follow that rule. It is handed `cfg` and `site`, and
+   * neither carries a domain — so a name built from `siteId` alone would let
+   * two domains that happen to use the same plant code block each other's
+   * channel. Silently, and looking exactly like "someone else holds it".
+   *
+   * So the name is composed here, where `domainId` and `instanceId` are known,
+   * and the rule lives in one place.
+   *
+   * ── Always present, unlike `cursor` ───────────────────────────────────────
+   * A feed needs its lease on the very first attach, before there is any
+   * cursor to carry. So this object is now handed over even when nothing has
+   * been read yet; `cursor` being absent is what still says "first attach",
+   * which is how every connector already reads it (`continuity?.cursor`).
+   */
+  leaseName: string
   /** 지난번에 어디까지 읽었나 — 없으면 첫 붙음이다(그때만 되돌아볼 날수로 창을 만든다). */
   cursor?: { streams?: Record<string, LiveFeedCursor>; firstAttachedAt?: string }
   /**
@@ -326,6 +457,25 @@ export interface LiveFeedContinuity {
   onWithheld?: (info: { reason: string; count: number }) => void
 }
 
+/**
+ * 저쪽이 조치를 받을 준비가 됐나 — **「모른다」를 「안 된다」로 답하지 않는다.**
+ *
+ * `ready` 가 거짓이면 `reason` 이 사람의 말로 무엇이 없는지 말하고, `code` 가 화면이 다음 할 일을
+ * 가를 값이다(문장을 파싱하지 않게 — 번역하면 문장이 바뀐다).
+ */
+export interface ActuationReadiness {
+  /** 받을 수 있어 보이나. **모르면 `undefined`** — 거짓이 아니다. */
+  ready?: boolean
+  /** 어디까지 봤나. `local` = 우리 설정만 봤다(망을 타지 않았다). `remote` = 저쪽에 물었다. */
+  checked: 'local' | 'remote'
+  /** 무엇이 없나 — 사람의 말로. */
+  reason?: string
+  /** 화면이 가를 값. 커넥터가 정한다(예: `no-endpoint` · `no-secret` · `unreachable` · `not-configured`). */
+  code?: string
+}
+
+import type { LiveCadence } from './live-cadence.js'
+
 export interface ReferenceAdapter {
   /** 레지스트리 키 (예: 'virtual' | 'sap-ewm' | 'custom-rest'). */
   type: string
@@ -346,6 +496,21 @@ export interface ReferenceAdapter {
    */
   masterSteps?: readonly ReferenceStep[]
 
+  /**
+   * 이 원천이 **축마다 언제·얼마나 자주 내놓나** — 유입 건강이 이 선언으로 견준다.
+   *
+   * 선언하지 않은 축은 **지금까지처럼** 창 하나(10분)로 견준다. 그러면 밤에 발전하지 않는
+   * 태양광과 업무시간만 도는 원천이 **정상인데 매일 밤 빨갛게** 난다 — 거짓 빨강이 쌓이면 진짜
+   * 빨강도 같이 안 읽힌다.
+   *
+   * `masterSteps` 와 같은 규율이다: **어댑터만 자기 시간의 결을 안다.** 호스트가 짐작하면 그것은
+   * 지어낸 판정이다.
+   *
+   * 자세한 것은 §`live-cadence.ts` — 특히 「해 있는 동안」을 **고정 시각으로 박지 말 것**
+   * (오늘 잰 일몰은 두 달 뒤에 틀리다).
+   */
+  liveCadence?: readonly LiveCadence[]
+
   /**
    * @param onStep 진행을 알리는 통로 — **선택이다.** 주지 않으면 예전과 같이 동작한다.
    *
@@ -432,7 +597,149 @@ export interface ReferenceAdapter {
    * `ref` 를 **반드시** 돌려준다. 그것이 없으면 넘긴 것이 저쪽에서 무엇이 되었는지 되짚을 수 없고,
    * 되돌릴 때 무엇을 되돌릴지 말할 수 없다.
    */
-  actuate?(cfg: ConnectionConfig, site: SiteDescriptor, command: ApprovedCommand): Promise<{ ok: boolean; ref?: string; error?: string }>
+  actuate?(
+    cfg: ConnectionConfig,
+    site: SiteDescriptor,
+    command: ApprovedCommand
+  ): Promise<{
+    ok: boolean
+    ref?: string
+    /**
+     * **받아들였으나 남은 것이 있다** — 실패가 아니다. 사람이 저쪽에서 해야 할 일이 있으면 여기 적는다.
+     *
+     * `error` 에 적지 말 것 — 실패로 읽혀 커맨드가 `failed` 로 앉고, 다시 넘기게 된다. 실제로 MES 가
+     * 「지시서를 못 붙였다」를 답했을 때 커넥터가 적을 칸이 없어 로그로만 남겼고, 트윈 쪽에서는 성공한
+     * 조치와 구별되지 않았다.
+     */
+    note?: string
+    /**
+     * 그 말 중 **다음에 할 일** 한 줄 — 원인은 위 `note` 다.
+     *
+     * 붙여 보내지 말 것. 읽는 사람은 「그래서 내가 뭘 해야 하나」를 먼저 찾고, 한 문장으로 오면
+     * **화면이 자르게 되며 자르는 규칙이 화면마다 생긴다.** 어댑터는 이미 둘로 알고 있다.
+     */
+    noteNext?: string
+    error?: string
+    /**
+     * **다시 해서 될 일인가** — 실패했을 때만.
+     *
+     *   again       그대로 다시 해 볼 만하다      못 닿았거나 저쪽이 잠깐 흔들렸다
+     *   after-fix   사람이 고친 뒤 그대로 나간다   설정 문제
+     *   never       이 조치로는 영원히 안 된다     지시 내용이 틀렸다
+     *
+     * 가르는 자리는 **「조치를 다시 낼 필요가 있나」**다. 설정이 틀린 것은 조치가 멀쩡하므로
+     * `after-fix`, 지시 내용이 틀린 것은 그 조치가 영원히 틀렸으므로 `never` 다.
+     *
+     * **문장에 담지 말 것** — 일꾼이 그것을 쓰려면 파싱해야 하고, 번역되면 깨진다.
+     *
+     * 말하지 않으면 일꾼이 **집지 않는다.** 모르는 것을 `never` 로 접으면 고칠 수 있는 것을 사람이
+     * 포기하고, `again` 으로 접으면 없는 자재를 끝없이 두드린다.
+     */
+    retry?: 'again' | 'after-fix' | 'never'
+  }>
+
+  /**
+   * **저쪽이 조치를 받을 준비가 됐나** — 보내기 전에 묻는다. 선택이다.
+   *
+   * ── 왜 필요한가 (2026-09-03 실측) ──────────────────────────────────────────
+   * 승인된 조치를 넘겼더니 저쪽이 503 을 답했다 — **저쪽 프로세스에 비밀값이 실려 있지 않았다.**
+   * 트윈 쪽 연결 설정에는 있었고, 주소도 맞았고, 서명도 맞았다. 저쪽이 재기동되면서 환경 변수에만
+   * 살던 값을 잃은 것이다.
+   *
+   * 그것을 보내 보기 전에는 알 수 없었다. 그래서 사람이 승인 화면까지 가서 누르고, 실패를 보고,
+   * 다시 로그인했다. **승인이 사라지지는 않는다**(`failed → dispatch` 가 열려 있다) — 없어진 것은
+   * 사람의 시간이다.
+   *
+   * ── 문이 아니다. 알림이다 ──────────────────────────────────────────────────
+   * **이 답으로 넘김을 막지 않는다.** 막으면 새 실패 방식이 생긴다 — 점검이 틀렸거나 잠깐 못 닿은
+   * 사이에, 성공할 수 있었던 조치가 못 나간다. 화면이 「지금 저쪽이 못 받는 것으로 보입니다」를
+   * 미리 말하는 데까지가 이 얼굴의 일이다.
+   *
+   * ── 두 겹을 구별한다 ──────────────────────────────────────────────────────
+   * 우리 쪽에 무엇이 없는 것(주소·비밀값을 설정하지 않았다)은 **망을 타지 않고** 알 수 있다.
+   * 저쪽이 받을 준비가 됐는지는 물어야 안다. 앞엣것만 답하고 뒤엣것을 안 물어도 되고, 그때
+   * `checked: 'local'` 로 그 사실을 말한다 — 「살아 있다」고 말한 적 없는 것과 「죽었다」는 다르다.
+   *
+   * 화면이 그릴 때마다 부를 수 있으므로 **망을 타는 구현은 짧게 끝내야 한다.**
+   */
+  actuationReadiness?(cfg: ConnectionConfig, site: SiteDescriptor): Promise<ActuationReadiness>
+
+  /**
+   * **놓친 구간을 backfill 한다** — 밀어 주는 길의 짝.
+   *
+   * ── 왜 필요한가 (2026-08-31, 인티그레이션 레인 지적) ──────────────────────
+   * 훅은 반드시 놓친다 — 우리가 내려가 있을 때, 그쪽이 못 보냈을 때, 네트워크가 끊겼을 때. 받는 쪽이
+   * 번호로 그것을 **알아채게** 되었지만(§`takeInSequence`), 알아챈 뒤 **그 사이를 채우는 길이 없었다.**
+   * 설계가 그 길을 적어 두었는데 만들지 않았다.
+   *
+   * ── 왜 `since` 가 번호인가 ────────────────────────────────────────────────
+   * 커서에 사는 것이 번호이고, 보내는 쪽이 되풀어 주는 단위도 번호다. 시각으로 두면 두 축이 섞이고,
+   * 같은 밀리초의 두 행이 갈리지 않는다.
+   *
+   * ── 왜 `scope` 를 프레임워크가 주나 ───────────────────────────────────────
+   * 그것이 커서 열쇠의 절반이다. 커넥터가 만들면 열쇠를 만드는 자리가 둘이 되고, 어긋난 그곳은 조용하다.
+   * 그래서 프레임워크가 커서에서 읽어 그대로 넘긴다.
+   *
+   * 답이 `InboundBatch` 인 이유도 하나다 — **backfill 한 것이 밀어 받은 것과 같은 번호 검사를 지난다.**
+   * 다른 모양으로 돌려주면 그 검사를 다시 만들게 되고, 두 길이 다른 규칙으로 받는다.
+   */
+  fetchSince?(cfg: ConnectionConfig, site: SiteDescriptor, scope: string, since: number): Promise<InboundBatch>
+
+  /**
+   * (선택) **원본에만 있는 관계를 조회한다** — 트윈으로 복제하지 않고 그때그때 물어본다.
+   *
+   * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+   * 트윈은 표준 어휘로 옮길 수 있는 것만 담는다. 원본에는 그 밖의 관계가 있다 — MES 의 생산 실적,
+   * 설비 상태 구간, 정비 계획. 설비 상세 화면에서 사람이 실제로 묻는 것이 그런 것들이다.
+   *
+   * 이것을 트윈으로 복제하면 원본의 표를 전부 미러링하게 된다. 조회용 참조는 복제하지 않고 그때
+   * 물어보는 것이 맞다.
+   *
+   * ── 왜 어댑터가 답하나 ──────────────────────────────────────────────────────
+   * 어느 테이블에 무엇이 있는지는 원본마다 다르다. 커널이 그것을 알면 원본 하나의 스키마에 묶이고,
+   * 다음 원본이 다른 구조를 쓰면 커널을 또 고친다.
+   *
+   * 어댑터는 이미 그 원본에 붙는 방법과 인증을 갖고 있다. 연결 설정이 한 자리에 있어야 한다는 것은
+   * `actuate` 를 별개 어댑터로 두지 않은 것과 같은 이유다.
+   *
+   * ── 실패하면 그것을 알린다 ──────────────────────────────────────────────────
+   * 예외를 던져도 됩니다. 호출하는 쪽이 잡아서 「조회 실패」로 표시하고, 나머지 관계는 그대로
+   * 표시합니다. 빈 배열은 「가리키는 것이 없다」는 뜻이고 실패와 다릅니다.
+   *
+   * @param axis   `equipment` · `locations` 등 계약의 축 이름
+   * @param itemId 그 축에서의 식별자. 원본이 아는 이름이다(설비는 `ops_equipment.name`)
+   */
+  fetchLinks?(cfg: ConnectionConfig, site: SiteDescriptor | undefined, axis: string, itemId: string): Promise<ReferenceLinkGroup[]>
+
+  /**
+   * (선택) **그 번호가 무엇이었나** — 구멍을 만났을 때 묻는다.
+   *
+   * ── 왜 필요한가 (2026-09-06 실물) ──────────────────────────────────────────
+   * 커넥터가 구멍을 만나면 「418 다음이 420」이라고만 말한다. **419 가 무엇이었는지 알 방법이
+   * 없다.** 그날 plant 레인이 자기 아웃박스를 손으로 뒤져서 그것이 부하 시험의 흔적임을 찾았다.
+   *
+   * 구멍은 채널을 세운다 — 그 뒤의 사실이 통째로 못 온다. 그래서 「이게 무엇이었나」가 급한 물음인데
+   * 물을 자리가 없었다.
+   *
+   * ── 세 가지를 가른다. 넷째는 「모른다」다 ──────────────────────────────────
+   * ```
+   * present    그 행이 있다 — 봉투를 함께 낸다
+   * lost       번호는 나갔는데 행이 없다 — 쓰기 하나를 잃었다
+   * unissued   아직 그 번호까지 안 갔다 — 잃은 것이 아니다
+   * unknown    원본이 그 셋을 구별하지 못한다
+   * ```
+   *
+   * **`unknown` 이 있어야 한다.** 채번을 따로 들지 않는 원본은 「행이 없다」에서 `lost` 와
+   * `unissued` 를 가를 수 없다. 그때 `lost` 로 단정하면 사람이 없는 사실을 찾으러 간다.
+   *
+   * ── 판정을 여기서 하지 않는다 ─────────────────────────────────────────────
+   * 이 문은 **원본이 아는 것을 그대로 낸다.** 「그러니 이 번호는 포기해도 된다」는 판정은 사람이
+   * 한다 — 그 판단은 되돌릴 수 없어서(커서가 지나가면 끝이다) 코드가 대신할 자리가 아니다.
+   *
+   * @param from 이 번호부터(포함)
+   * @param to   이 번호까지(포함). 원본이 상한을 두면 그만큼만 내고 `truncated` 로 말한다
+   */
+  seqReport?(cfg: ConnectionConfig, site: SiteDescriptor | undefined, scope: string, from: number, to: number): Promise<SeqReport>
 
   openLiveFeed?(
     cfg: ConnectionConfig,
@@ -542,6 +849,12 @@ export function capabilitiesOf(adapter: ReferenceAdapter | undefined): Reference
   const out: ReferenceCapability[] = []
   if (declared.has('live') && typeof adapter.openLiveFeed === 'function') out.push('live')
   if (declared.has('control') && typeof adapter.control === 'function') out.push('control')
+  if (declared.has('actuate') && typeof adapter.actuate === 'function') out.push('actuate')
+  /*
+   * **선언만으로 성립한다** — 부를 메서드가 없다. 「두 번 해도 같은가」는 어댑터가 하는 일이 아니고
+   * 저쪽 시스템의 성질이다. 그래서 구현 검사를 하지 않는다.
+   */
+  if (declared.has('idempotent-actuation')) out.push('idempotent-actuation')
   return out
 }
 
@@ -569,8 +882,17 @@ const adapters = new Map<string, ReferenceAdapter>()
  */
 export function registerAdapterType(adapter: ReferenceAdapter): void {
   const declared = new Set(adapter.capabilities ?? [])
-  const undeclared = (['live', 'control'] as const).filter(
-    c => typeof (adapter as any)[c === 'live' ? 'openLiveFeed' : 'control'] === 'function' && !declared.has(c)
+  /* 능력 이름과 그것을 증명하는 메서드 — **한 자리에 적는다.** 두 벌이면 새 능력이 한쪽에만 늘어난다. */
+  const METHOD_OF: Record<ReferenceCapability, string> = {
+  live: 'openLiveFeed',
+  control: 'control',
+  actuate: 'actuate',
+  /* 성질 선언이라 부를 메서드가 없다 — 어댑터가 `capabilities` 에 적는 것으로 끝난다. */
+  'idempotent-actuation': ''
+}
+  const undeclared = (Object.keys(METHOD_OF) as ReferenceCapability[]).filter(
+    /* 메서드 이름이 없는 능력(선언만으로 성립하는 것)은 이 경고의 대상이 아니다. */
+    c => METHOD_OF[c] !== '' && typeof (adapter as any)[METHOD_OF[c]] === 'function' && !declared.has(c)
   )
   if (undeclared.length) {
     twinWarn(

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

@@ -0,0 +1,165 @@
+/*
+ * **빠진 구간을 다시 받는 일을 실제로 부른다** — `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 { pushCursorKey, withSeq } from './hook-contract.js'
+import { fillSince, type FillOutcome } from './reference-fill.js'
+import { liveIngest } from './live-ingest.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)
+
+  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)
+    },
+    ...(maxPages ? { maxPages } : {})
+  })
+
+  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) }
+}