@things-factory/headless-twin 10.0.19 → 10.1.0

package/server/engine/oee-accumulator.ts

@@ -11,8 +11,8 @@
  * 시간축 = Date.parse(eventTime)(ms) — 구간 차분은 sim/실시간 무관하게 정확(고정 오프셋 상쇄).
  */
 /* OEE 공식은 계약에 있다 — 소비자가 셋이라(시뮬·미러·MES) 커널에 두면 밖에서 다시 쓰게 된다. */
-import { computeOee } from '@operato/ops-contract'
-import type { OeeCounters } from '@operato/ops-contract'
+import { computeOee, nonWorkingMsIn } from '@operato/ops-contract'
+import type { OeeCounters, WorkCalendarEntry } from '@operato/ops-contract'
 import type { CanonicalEnvelope, OeeMetrics } from '@operato/ops-contract'
 
 interface Acc {
@@ -22,7 +22,7 @@ interface Acc {
   busyMs: number
   downMs: number
   goodCount: number
-  scrapCount: number
+  nonconformingCount: number
 }
 
 /** 누적기의 완전한 재개점 — 저장했다 되살릴 수 있어야 꼬리만 계산할 수 있다. */
@@ -35,10 +35,68 @@ export class OeeAccumulator {
   private acc = new Map<string, Acc>()
   private maxMs = 0 // 최신 이벤트 시각 — nowMs 기본값(현재 계측 시점)
 
+  /*
+   * ── 현장이 언제 도나 — **계획 조업 시간의 근거** (2026-09-07) ────────────────
+   * 이것이 없던 동안 계획 조업 시간이 「재기 시작한 뒤 흐른 시간 전부」였다. 주말도 야간도 휴일도
+   * 계획 조업으로 세었다.
+   *
+   * [산술] 8시간 × 주5일이면 168시간 중 40시간이 조업이다 — PBT 가 4.2배 크고 가동률이 그만큼 작다.
+   * 그리고 그 수가 1로 잘려 있어서(오늘 걷었다) 그럴싸하게 보였다. 두 오류가 서로를 가렸다.
+   *
+   * plant 레인이 같은 자리를 먼저 겪고 실측을 냈다 — 3교대를 물려받으면 `availability 0.4583`,
+   * 달력이 아예 없으면 **수를 안 낸다**. 트윈은 창 전체를 계획으로 쳐서 수를 냈다.
+   *
+   * ⚠ **선언이 없으면 채우지 않는다.** `nonWorkingMsIn` 이 그때 `undefined` 를 내고, 그 값을 0 으로
+   * 바꾸지 않는다 — 0 은 「달력을 봤고 쉬는 시간이 없었다」는 주장이다. 지금은 그러면 PBT 가 창 전체가
+   * 되어 예전과 같은 수가 나온다. **그것을 「안 낸다」로 바꿀지는 아직 결정되지 않았다** — 거동 변화가
+   * 크고 화면이 비는 자리라 사용자 판단을 기다린다(성숙도에 미달로 세우는 짝과 함께 가야 한다).
+   */
+  private siteCalendar?: readonly WorkCalendarEntry[]
+  private calendarByResource = new Map<string, readonly WorkCalendarEntry[]>()
+  private utcOffsetMinutes?: number
+
+  /**
+   * 모델에서 조업 달력을 읽어 얹는다 — 모델을 들고 있는 쪽(`TwinEngine`)이 부른다.
+   *
+   * ── 우선순위가 여기 있는 이유 ───────────────────────────────────────────────
+   * ```
+   * 설비의 달력    이 설비의 가동 계획 — 선언했으면 이것이 이긴다 (24시간 도는 로)
+   * 현장의 달력    이 현장의 조업일
+   * 없음          제약 없음 — 계획 조업 시간이 창 전체가 된다
+   * ```
+   * 계획 조업 시간을 내는 자리가 여기라 그 규칙도 여기 둔다. 부르는 쪽마다 고르게 하면 라이브와
+   * 히스토리가 다른 답을 낸다.
+   *
+   * ⚠ **설비의 달력은 사람의 근무조가 아니다.** 씨앗이 사람의 근무조를 설비 달력에 복사한 일이 있었고,
+   * 그때 아무도 근무하지 않는 시간이 근무 시간으로 기록됐다. 사람 쪽은 `persons[].workCalendar` 다.
+   *
+   * 세우는 자리에서 한 번만 주지 않고 따로 부르는 이유는 모델이 다시 실릴 수 있기 때문이다
+   * (재동기화 · 이관). 그때 달력만 갈아 끼우면 누적된 계측을 버리지 않는다.
+   */
+  setWorkCalendar(model?: { workCalendar?: readonly WorkCalendarEntry[]; equipment?: readonly any[]; utcOffsetMinutes?: number }): void {
+    this.siteCalendar = model?.workCalendar?.length ? model.workCalendar : undefined
+    this.utcOffsetMinutes = model?.utcOffsetMinutes
+    this.calendarByResource.clear()
+    for (const e of model?.equipment ?? []) {
+      const cal = e?.workCalendar
+      if (e?.id && Array.isArray(cal) && cal.length) this.calendarByResource.set(String(e.id), cal)
+    }
+  }
+
+  /**
+   * 이 설비의 계획 가동 달력 — 자기 것이 있으면 그것, 없으면 현장의 것.
+   *
+   * 인자 이름이 `moverId` 인 것은 **봉투의 옛 세대 필드 이름**이라 그렇다(§`apply`). 새로 만드는
+   * 이름에는 그 낱말을 쓰지 않는다 — 어휘 가드가 그것을 잡았고, 맞게 잡았다.
+   */
+  private calendarFor(moverId: string): readonly WorkCalendarEntry[] | undefined {
+    return this.calendarByResource.get(moverId) ?? this.siteCalendar
+  }
+
   private ensure(moverId: string, t: number): Acc {
     let a = this.acc.get(moverId)
     if (!a) {
-      a = { lastMs: t, startMs: t, busyMs: 0, downMs: 0, goodCount: 0, scrapCount: 0 }
+      a = { lastMs: t, startMs: t, busyMs: 0, downMs: 0, goodCount: 0, nonconformingCount: 0 }
       this.acc.set(moverId, a)
     }
     return a
@@ -70,11 +128,11 @@ export class OeeAccumulator {
     const t = Date.parse(env.eventTime)
     if (t > this.maxMs) this.maxMs = t
     if (env.eventType === 'quality.output') {
-      const q = env.data as { moverId?: string; goodCount?: number; scrapCount?: number }
+      const q = env.data as { moverId?: string; goodCount?: number; nonconformingCount?: number }
       if (!q?.moverId) return
       const a = this.ensure(q.moverId, t)
       a.goodCount = q.goodCount ?? a.goodCount // 누적값 최신화(good/scrap 은 무버 누적)
-      a.scrapCount = q.scrapCount ?? a.scrapCount
+      a.nonconformingCount = q.nonconformingCount ?? a.nonconformingCount
       return
     }
     if (env.eventType !== 'equipment.status') return
@@ -97,13 +155,27 @@ export class OeeAccumulator {
      * 화면에 `idleMs 1767226603000`(약 56,000년) 유휴가 섰다. 창을 **말하지 않는다** — 공식이
      * 없음을 없음으로 다룬다(§computeOee).
      */
-    if (!a) return { runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0 }
+    if (!a) return { runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, nonconformingCount: 0 }
     const dt = Math.max(0, nowMs - a.lastMs)
     let busyMs = a.busyMs
     let downMs = a.downMs
     if (a.status === 'busy') busyMs += dt
     else if (a.status === 'down') downMs += dt
-    return { runMs: busyMs, setupMs: 0, downMs, goodCount: a.goodCount, scrapCount: a.scrapCount, metricsSinceMs: a.startMs }
+    /*
+     * 계획 정지 — 계약이 이 칸에 그 뜻을 적어 뒀다(점심 · 예방보전 · 교대). 휴일과 주말이 같은
+     * 갈래다. `metricsSinceMs` 를 당겨서 같은 효과를 내지 않는다: 그 칸은 「언제부터 쟀나」라는
+     * 사실이고, 파생값을 얹으면 실제보다 늦게 재기 시작했다고 말하는 것이 된다.
+     */
+    const holdMs = nonWorkingMsIn(this.calendarFor(moverId), a.startMs, nowMs, this.utcOffsetMinutes)
+    return {
+      runMs: busyMs,
+      setupMs: 0,
+      downMs,
+      goodCount: a.goodCount,
+      nonconformingCount: a.nonconformingCount,
+      metricsSinceMs: a.startMs,
+      ...(holdMs !== undefined ? { holdMs } : {})
+    }
   }
 
   /** 공유 공식으로 근사 OEE 산출 — 정확한 OEE 는 실 텔레메트리(option ①). nowMs 기본=최신 이벤트 시각. */

package/server/engine/twin-engine.ts

@@ -70,6 +70,7 @@ import {
   recordIngestSource,
   recordDuplicates,
   rollIngestWindow,
+  recordVocabulary,
   /* 별칭 — 같은 이름의 정적 메서드와 헷갈리지 않게(그 메서드가 이것을 부른다). */
   recordJournalWrite as recordLedgerWrite,
   type IngestHealthView,
@@ -1799,8 +1800,23 @@ export class TwinEngine {
    * `timezone` 을 읽는다. 공간이 말하지 않으면 **테넌트로 내려가지 않는다** — 잘못된 입자로 답하는 것이
    * 모르는 것보다 나쁘다(그때는 커널이 UTC 로 읽고, 그 기본값은 계약에 밝혀져 있다).
    *
-   * 커널은 zero-dep 이라 시간대 데이터베이스를 갖지 않으므로 **분 오프셋**으로 풀어 넘긴다. 그 값은
-   * 지금 계절의 것이다(일광절약시간) — 계절을 넘는 긴 예측은 한 시간 어긋난다(계약에 명시).
+   * 커널은 zero-dep 이라 시간대 데이터베이스를 갖지 않으므로 **분 오프셋**으로 풀어 넘긴다.
+   *
+   * ── 이름도 함께 얹는다 (2026-09-07) ────────────────────────────────────────
+   * 오프셋 하나만 얹으면 **그 값이 이 순간의 것으로 모델에 굳는다.** 트윈은 몇 주씩 돌고, 자료에
+   * 이미 `America/Tijuana`(PST −480 / PDT −420)가 있다 — 여름에 뜬 트윈이 11월까지 돌면 그 뒤 모든
+   * 시각이 한 시간 틀린다.
+   *
+   * 지난 구간을 접을 때가 더 나쁘다. 1년치를 교대별로 접으면 그 1년을 한 오프셋으로 읽는데 그 안에
+   * 전환이 두 번 있다. 어긋난 시각이 오류를 내지 않고 **다른 교대로 세어진다.**
+   *
+   * 그래서 이름(`timezone`)을 함께 얹어, 순간마다 다시 풀 수 있게 한다. 커널은 이 값을 쓰지 않는다 —
+   * 여전히 오프셋을 호출마다 받는다. 푸는 것은 호스트의 몫이고 그것이 계약이 적어 둔 분담이다.
+   *
+   * `utcOffsetMinutes` 도 계속 얹는다. 아직 이름을 안 보는 소비처가 그 값으로 돌고, 이름이 없는 공간에
+   * 대해서는 그것이 유일한 답이다.
+   *
+   * ⚠ 이것으로도 완전하지 않다. 정확한 답은 호스트가 표준대로 **절대 구간**을 계산해 넣는 것이다.
    */
   static async withSpaceTimeBase(model: TwinModelDef, domainId: string, spaceId?: string): Promise<TwinModelDef> {
     const sid = spaceId ?? (model as any)?.spaceId
@@ -1811,7 +1827,8 @@ export class TwinEngine {
       if (space?.timezone) twinWarn(`[twin-engine] space "${sid}" declares time zone "${space.timezone}" but it is not a known IANA zone — times will be read as UTC.`)
       return model
     }
-    return { ...model, utcOffsetMinutes: offset }
+    /* 이름이 IANA 로 읽히는 것을 위에서 이미 확인했다 — 오프셋이 나왔다는 것이 그 증거다. */
+    return { ...model, utcOffsetMinutes: offset, timezone: space!.timezone }
   }
 
   static startLive(id: string, domainId: string, kind: string, model: TwinModelDef): InstanceRuntime {
@@ -1829,7 +1846,13 @@ export class TwinEngine {
     /* `projector` 필드는 옛 이름으로 남긴다 — 소비처가 `snapshot()` 을 부르므로 얇은 어댑터로 잇는다.
      * (P3 에서 소비처를 커널 어휘로 바꾸면 사라진다.) */
     const projector = { apply: (e: CanonicalEnvelope) => kernel.apply(e), snapshot: () => kernel.getSnapshot() }
-    const inst: InstanceRuntime = { id, domainId, mode: 'live', restartPolicy: 'resync', kernel, projector, oee: new OeeAccumulator(), spaceId: (model as any)?.spaceId, model, unsub: () => {} }
+    const oeeAcc = new OeeAccumulator()
+    /*
+     * **현장의 조업 달력을 얹는다** — 이것을 안 부르면 계획 조업 시간이 창 전체가 된다(§`OeeAccumulator`).
+     * 자리를 만들고 부르지 않는 것이 이 저장소에서 가장 자주 나는 결함이라, 세우는 자리에서 바로 붙인다.
+     */
+    oeeAcc.setWorkCalendar(model as any)
+    const inst: InstanceRuntime = { id, domainId, mode: 'live', restartPolicy: 'resync', kernel, projector, oee: oeeAcc, spaceId: (model as any)?.spaceId, model, unsub: () => {} }
     /*
      * ── 커널이 **판정으로 낸 사실**도 저널에 남는다 (2026-08-14 실측으로 잡음) ────
      *
@@ -3923,6 +3946,12 @@ export class TwinEngine {
      * 가동 이력이 나온다(그 뒤에 일어난 고장이 과거 화면에 섞이지 않는다).
      */
     const oee = new OeeAccumulator()
+    /*
+     * 히스토리도 같은 달력으로 읽는다 — 라이브와 다른 기준으로 세면 두 화면이 다른 수를 보인다.
+     * 여기서 쓸 모델은 `newest` 다(이 스코프의 마지막 구조). 구간마다의 `model` 은 위 루프 안에만
+     * 있고, 달력은 구조 개정마다 갈리는 값이 아니다.
+     */
+    oee.setWorkCalendar(newest as any)
     /* 재개점이 있으면 그 위에 꼬리만 얹는다 — 없으면 꼬리분만 세어 가용률이 알리지 않고 작아진다. */
     if (resume?.fold?.oee) oee.restore(resume.fold.oee)
     for (const r of wanted) {
@@ -4306,6 +4335,35 @@ export class TwinEngine {
     return !!this.instances[runtimeKey(domainId, id)]
   }
 
+  /**
+   * 이 트윈의 **중복 판정 기억을 미리 채운다** — 저널에서 읽은 정체로.
+   *
+   * 기억은 프로세스 안에만 있어서 재기동하면 비워진다(§`FactDeduper`). 그 뒤 backfill 을 돌리면
+   * 이미 저널에 있는 사실도 「처음 본 것」이 되어 다시 앉는다. 실측으로 39건이 통째로 다시 앉았다
+   * (2026-09-06, `mes-line-a`).
+   *
+   * 안 도는 트윈에는 채울 곳이 없다 — 0을 낸다(거짓이 아니라 사실이다).
+   */
+  static warmDeduper(domainId: string, id: string, identities: readonly string[]): number {
+    const inst = this.instances[runtimeKey(domainId, id)]
+    if (!inst || !identities.length) return 0
+    return (inst.deduper ??= new FactDeduper()).remember(identities)
+  }
+
+  /**
+   * 이 프로세스가 지금 들고 있는 트윈들 — 테넌트로 좁혀서.
+   *
+   * 주기 작업(규칙 판정 등)이 「무엇을 돌아야 하나」를 물을 자리다. 등록부(DB)를 읽으면 **다른 프로세스가
+   * 든 트윈까지 나온다** — 그것을 돌면 같은 조치가 두 벌 올라간다. 도는 것은 든 쪽이 돈다.
+   *
+   * `owns()` 와 같은 술어를 쓴다(`this.instances`). 두 벌이면 어긋난다.
+   */
+  static ownedTwins(domainId?: string): { domainId: string; instanceId: string }[] {
+    return Object.entries(this.instances)
+      .map(([key, inst]) => ({ domainId: inst.domainId, instanceId: parseRuntimeKey(key).instanceId }))
+      .filter(t => !domainId || t.domainId === domainId)
+  }
+
   /**
    * 이 트윈이 이 테넌트 것인가 — **떠 있든 아니든.**
    *
@@ -4475,6 +4533,52 @@ export class TwinEngine {
     this.onWindowClosed = fn
   }
 
+  /**
+   * **모든 트윈의 창을 굴린다** — 보는 사람이 없어도 창이 닫히게.
+   *
+   * ── 무엇이 있었나 (2026-09-05 실측) ────────────────────────────────────────
+   * 창은 「다음 사건이 왔을 때 이전 창을 닫는」 모양으로만 굴렀다. 그러면 사실이 드문 트윈은 창이
+   * 계속 열려 있고, 표에 아무것도 안 남는다. 두 수가 그것을 정확히 말한다.
+   *
+   *   mes-miratek   사실 46건 · 62분에 흩어짐   창  1개
+   *   mes-line-a    사실 11건                   창 48개
+   *
+   * **사실 수와 창 수가 거꾸로다.** 창을 만든 것이 유입이 아니라 **누가 물어본 것**이다 —
+   * `ingestHealthOf()` 가 굴리므로, 점검표·화면이 계속 묻는 트윈만 기록이 쌓였다.
+   *
+   * 그래서 **아무도 안 보는 트윈일수록 기록이 없다.** 사실이 조용히 사라지는 것을 잡으려고 만든
+   * 장부가 정확히 그 반대로 돌고 있었다. 실제로 137봉투가 장부 없이 지나갔다(인티그레이션 레인 실측).
+   *
+   * ── 왜 주기인가 ────────────────────────────────────────────────────────────
+   * 창이 닫히는 이유는 **시간이 지난 것**이다. 사건도 질의도 그것을 알려 주는 신호일 뿐이고, 둘 다
+   * 안 올 수 있다. 시간은 늘 지나므로 주기가 그 사실에 맞는 신호다.
+   *
+   * 조용한 트윈이 자기 침묵을 기록하게 되는 것이 이 변경의 값이다 — `expected-quiet` 판정이 그
+   * 기록 위에 선다.
+   */
+  static rollAllIngestWindows(nowMs: number = Date.now()): number {
+    let closed = 0
+    for (const key of Object.keys(this.ingestLedgers)) {
+      const ledger = this.ingestLedgers[key]
+      if (!ledger) continue
+      /*
+       * 키가 깨져 있으면 그 트윈만 건너뛴다 — 하나 때문에 나머지 장부가 안 굴러서는 안 된다.
+       * 훅의 실패도 `rollIngestWindow` 가 감싼다(영속을 지키려고 관측을 멈추지 않는다).
+       */
+      let at: { domainId: string; instanceId: string }
+      try {
+        at = parseRuntimeKey(key)
+      } catch {
+        continue
+      }
+      rollIngestWindow(ledger, nowMs, undefined, w => {
+        closed++
+        this.onWindowClosed?.(at, w)
+      })
+    }
+    return closed
+  }
+
   /**
    * 한 번의 인제스트 결과를 장부에 적는다.
    *
@@ -4541,7 +4645,15 @@ export class TwinEngine {
      *
      * 「통과」로 세지 않는다 — 트윈이 멈춘 사이 사실이 사라지는데 화면이 100% 라고 말하게 된다.
      */
-    undelivered = 0
+    undelivered = 0,
+    /**
+     * **저널에 안 간 어휘 요소의 수** — 로트 번호·소비기한처럼 시각축이 없는 값.
+     *
+     * 사라진 것이 아니라 저널로 가지 않는 것이다. 그런데 그 수를 빼 주는 자리가 없으면
+     * 「보낸 것 − 앉은 것」이 안 맞고 **그 차이를 사라진 것으로 읽게 된다**(2026-09-05 실측:
+     * 커서 20 · 저널 17 · 어휘 1 을 사람이 손으로 세서 「둘이 빈다」를 찾았다).
+     */
+    vocabulary = 0
   ): void {
     const key = runtimeKey(domainId, instanceId)
     const ledger = this.ingestLedgers[key] ?? (this.ingestLedgers[key] = newIngestLedger())
@@ -4553,6 +4665,8 @@ export class TwinEngine {
       closed => this.onWindowClosed?.({ domainId, instanceId }, closed),
       undelivered
     )
+    /* 창을 이미 굴린 뒤라 순서가 중요하다 — 먼저 적으면 한 유입이 두 창에 걸친다. */
+    recordVocabulary(ledger, vocabulary)
   }
 
   /**

package/server/index.ts

@@ -9,6 +9,9 @@ import './routes.js'
 import { TwinEngine } from './engine/index.js'
 import { resumeReferenceLiveFeeds } from './service/reference/reference-live.js'
 import { installIngestWindowWriter } from './service/twin-ingest-window/index.js'
+import { installReferenceLinkResolver } from './service/reference/reference-links.js'
+import { startActuationRuleLoop } from './service/actuation/rule-loop.js'
+import { startFillLoop } from './service/reference/fill-loop.js'
 
 /*
  * 모듈 부팅 — **도는 트윈을 되살린다.**
@@ -26,6 +29,11 @@ process.on('bootstrap-module-start' as any, async ({ app, config, client }: any)
      * 남는다. 커널 층은 저장 계층을 모르므로 이 등록이 그 둘을 잇는 유일한 자리다.
      */
     installIngestWindowWriter()
+    /*
+     * 원본에만 있는 관계를 조회하는 문을 연다 — MES 의 생산 실적·정비 계획처럼 트윈이 담지 않는
+     * 것들. 조회용 참조는 트윈으로 복제하지 않고 그때 물어본다.
+     */
+    installReferenceLinkResolver()
     /*
      * **저널 보존 기간은 선언에서 온다** — 코드에 박아 두지 않는다(2026-08-22).
      *
@@ -54,6 +62,21 @@ process.on('bootstrap-module-start' as any, async ({ app, config, client }: any)
 
     await TwinEngine.bootstrap()
     await resumeReferenceLiveFeeds()
+    /*
+     * 빠진 구간을 다시 받는 주기 — 기동에서 한 번, 그 뒤 10분마다(§`fill-loop.ts`).
+     * 피드를 붙인 **뒤에** 세운다: 커널이 되살아나기 전에 부르면 도는 트윈이 0개다.
+     */
+    startFillLoop()
+
+    /*
+     * 조치 규칙 주기 — **트윈이 다 선 뒤에** 세운다. 앞에 세우면 첫 바퀴가 아직 안 선 트윈들을 돌고
+     * 「상태를 읽을 수 없다」를 규칙 행에 적는다. 그것은 사실이지만 사람에게는 오해다.
+     *
+     * 커널 틱과 따로 돈다 — 틱은 예외가 나면 그 트윈을 멈추고, 규칙 하나가 잘못됐다고 공장이 멈추면
+     * 안 된다(§`rule-loop.ts`).
+     */
+    startActuationRuleLoop()
+
     twinLog('Headless Twin host has started.')
   } catch (ex) {
     twinError('Headless Twin host failed to start.', ex)

package/server/migrations/1786600000000-RenameOperatoMesAdapterType.ts

@@ -0,0 +1,66 @@
+import { MigrationInterface, QueryRunner } from 'typeorm'
+
+/**
+ * `twin_references.adapter_type` — `operato-mes` → `operato-plant`.
+ *
+ * ── 왜 마이그레이션이 필요한가 ────────────────────────────────────────────────
+ * 커넥터의 `type` 은 **저장되는 식별자**다. 트윈을 원본에 붙일 때 그 문자열이 이 컬럼에 적히고,
+ * 넘길 때·라이브를 열 때 그 값으로 커넥터를 찾는다(§`getAdapter`).
+ *
+ * 그래서 제품 개명(`operato-mes` → `operato-plant`)이 코드만 바뀌면 **이미 붙어 있는 원본이 커넥터를
+ * 못 찾는다.** 그때 나오는 것은 이렇다.
+ *
+ *   조치 넘김    `no-adapter` 로 거절
+ *   라이브       커넥터가 없어 관측이 끊긴다
+ *   화면         「등록되지 않은 커넥터입니다 (operato-mes)」 한 줄
+ *
+ * **오류는 안 나고, 원인이 개명이라는 것이 그 문장에 없다.** 트윈은 그대로 서 있고 값만 안 온다.
+ * 이 저장소에서 개명이 저장된 식별자에 닿았을 때 늘 이 모양으로 났다(보드 키·씬 컴포넌트 타입).
+ *
+ * ── 왜 이 패키지인가 ─────────────────────────────────────────────────────────
+ * 표를 든 쪽이 이 패키지다(`twin_references`). 커넥터는 `operato-twin` 이 등록하지만, 그 값이 사는
+ * 자리는 여기다. 마이그레이션은 표를 든 패키지에 둔다.
+ *
+ * ── 되돌리기 ─────────────────────────────────────────────────────────────────
+ * `down` 이 값을 되돌린다. 옛 코드로 되돌아가는 경우가 실제로 있고(배포 롤백), 그때 값이 새 이름으로
+ * 남아 있으면 같은 결함이 반대 방향으로 난다.
+ *
+ * 멱등: 해당하는 행이 없으면 아무것도 하지 않는다. TypeORM 질의 빌더만 쓴다 — 드라이버마다 파라미터
+ * 표기가 다르므로 raw SQL 을 쓰지 않는다.
+ */
+const REFS = 'twin_references'
+const COLUMN = 'adapter_type'
+/**
+ * 질의 빌더에는 **속성 이름**을 준다.
+ *
+ * 처음에 컬럼 이름(`adapter_type`)으로 썼더니 TypeORM 이 표 이름을 엔티티(`TwinReference`)로 풀고
+ * 「그런 속성이 없다」로 거절했다 — 표 이름을 주더라도 매핑은 엔티티 기준이다. 컬럼 이름은 표가
+ * 있는지 볼 때만 쓴다.
+ */
+const PROPERTY = 'adapterType'
+const OLD = 'operato-mes'
+const NEW = 'operato-plant'
+
+async function rename(queryRunner: QueryRunner, from: string, to: string): Promise<void> {
+  /* 표가 아직 없는 배포(첫 기동)에서는 할 일이 없다. */
+  const table = await queryRunner.getTable(REFS)
+  if (!table?.columns.some(c => c.name === COLUMN)) return
+
+  /* 객체 형태로 준다 — 문자열 조건은 드라이버마다 식별자 인용이 달라 그대로 나간다. */
+  await queryRunner.manager
+    .createQueryBuilder()
+    .update(REFS)
+    .set({ [PROPERTY]: to })
+    .where({ [PROPERTY]: from })
+    .execute()
+}
+
+export class RenameOperatoMesAdapterType1786600000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await rename(queryRunner, OLD, NEW)
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await rename(queryRunner, NEW, OLD)
+  }
+}

package/server/migrations/1786700000000-AddDispatchRetryColumns.ts

@@ -0,0 +1,82 @@
+/*
+ * 조치 표에 **일꾼이 쓸 네 칸**을 더한다.
+ *
+ * ── 왜 표에 두나 ────────────────────────────────────────────────────────────
+ * 물러섬을 메모리에 두면 재기동에 사라지고, 그러면 물러서던 것이 전부 즉시 재시도가 된다. 그리고
+ * 일꾼이 여러 대가 되면 같은 답을 봐야 한다.
+ *
+ *   dispatch_note_next   저쪽 말 중 「다음에 할 일」 한 줄 — 원인은 dispatch_note
+ *   retry                다시 해서 될 일인가 (again · after-fix · never)
+ *   attempts             몇 번 넘겨 봤나 — 목록의 「몇 번 해 봤나」
+ *   next_attempt_at      다음에 넘겨 볼 시각(ISO)
+ *
+ * ── 타입을 짐작하지 않는다 ──────────────────────────────────────────────────
+ * 엔티티가 `@Column({ nullable: true })` 로 두면 그것이 어느 컬럼 타입이 되는지는 **드라이버마다
+ * 다르다.** `'varchar'` 라고 적으면 sqlite·postgres·mysql 에서는 맞고 MSSQL·Oracle 에서 어긋난다.
+ *
+ * 그래서 같은 성질로 **이미 서 있는 형제 칸**의 타입을 읽어 그대로 쓴다 — 드라이버가 스스로 고른
+ * 답이라 다섯 곳에서 다 맞는다. 형제가 없으면 짐작하지 않고 멈춘다.
+ *
+ *   글자 셋   dispatch_note 에서
+ *   수 하나   effect_seen 에서
+ *
+ * plant 레인이 오늘 `equipmentClassIds` 마이그레이션에서 같은 방법을 썼다.
+ *
+ * ── 멱등 ────────────────────────────────────────────────────────────────────
+ * 칸이 이미 있으면 아무것도 하지 않는다 — 개발 sqlite 는 엔티티 선언만으로 이미 만들어 둔다.
+ * 표가 아직 없는 첫 기동에서도 할 일이 없다.
+ */
+import { MigrationInterface, QueryRunner, TableColumn } from 'typeorm'
+
+const TABLE = 'twin_command_records'
+
+/** 글자 칸의 형제 — 같은 성질(선택·자유 문자열)로 이미 서 있다. */
+const TEXT_SIBLING = 'dispatch_note'
+/** 수 칸의 형제 — 선택·정수. */
+const INT_SIBLING = 'effect_seen'
+
+const TEXT_COLUMNS = ['dispatch_note_next', 'retry', 'next_attempt_at'] as const
+const INT_COLUMNS = ['attempts'] as const
+
+export class AddDispatchRetryColumns1786700000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    const table = await queryRunner.getTable(TABLE)
+    if (!table) return /* 첫 기동 — 엔티티가 만든다 */
+
+    const typeOf = (sibling: string): string | undefined => table.columns.find(c => c.name === sibling)?.type
+
+    const textType = typeOf(TEXT_SIBLING)
+    const intType = typeOf(INT_SIBLING)
+
+    /*
+     * 형제가 없으면 **멈춘다.** 짐작한 타입으로 칸을 세우면 어느 드라이버에서 어긋나는지 개발에서
+     * 안 잡히고, 그 배포에서만 난다.
+     */
+    if (!textType || !intType) {
+      throw new Error(
+        `${TABLE} 에서 형제 칸을 못 찾았습니다 — ${TEXT_SIBLING}(${textType ?? '없음'}) · ` +
+          `${INT_SIBLING}(${intType ?? '없음'}). 타입을 짐작하지 않고 멈춥니다`
+      )
+    }
+
+    for (const name of TEXT_COLUMNS) {
+      if (table.columns.some(c => c.name === name)) continue
+      await queryRunner.addColumn(TABLE, new TableColumn({ name, type: textType, isNullable: true }))
+    }
+
+    for (const name of INT_COLUMNS) {
+      if (table.columns.some(c => c.name === name)) continue
+      await queryRunner.addColumn(TABLE, new TableColumn({ name, type: intType, isNullable: true }))
+    }
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    const table = await queryRunner.getTable(TABLE)
+    if (!table) return
+
+    for (const name of [...TEXT_COLUMNS, ...INT_COLUMNS]) {
+      if (!table.columns.some(c => c.name === name)) continue
+      await queryRunner.dropColumn(TABLE, name)
+    }
+  }
+}

package/server/migrations/index.ts

@@ -8,6 +8,8 @@ import { CarryLiveFeedCursor1786200000000 } from './1786200000000-CarryLiveFeedC
 import { IndexEventTypeByTime1786300000000 } from './1786300000000-IndexEventTypeByTime.js'
 import { IndexEventCreatedAt1786400000000 } from './1786400000000-IndexEventCreatedAt.js'
 import { CreateTwinSubjectEvents1786500000000 } from './1786500000000-CreateTwinSubjectEvents.js'
+import { AddDispatchRetryColumns1786700000000 } from './1786700000000-AddDispatchRetryColumns.js'
+import { RenameOperatoMesAdapterType1786600000000 } from './1786600000000-RenameOperatoMesAdapterType.js'
 
 export const migrations = [
   RenameTwinInstanceBoardToModel1786000000000,
@@ -15,5 +17,7 @@ export const migrations = [
   CarryLiveFeedCursor1786200000000,
   IndexEventTypeByTime1786300000000,
   IndexEventCreatedAt1786400000000,
-  CreateTwinSubjectEvents1786500000000
+  CreateTwinSubjectEvents1786500000000,
+  RenameOperatoMesAdapterType1786600000000,
+  AddDispatchRetryColumns1786700000000
 ]

package/server/routes.ts

@@ -15,8 +15,8 @@
  * 대신 **연결마다 비밀값**을 두고 그것으로 확인한다. 비밀값을 선언하지 않은 연결은 훅을 받지 않는다 —
  * 인증 없는 입구를 열어 두는 것보다 훅을 못 쓰는 것이 낫다.
  */
-import { ingestCanonicalRecords } from './engine/canonical-ingest.js'
-import { TwinEngine } from './engine/twin-engine.js'
+import { liveIngest } from './service/reference/live-ingest.js'
+import { requestFill } from './service/reference/fill-loop.js'
 import { handleHook } from './service/reference/reference-hook.js'
 import { databaseStore } from './service/reference/hook-store.js'
 
@@ -50,28 +50,16 @@ process.on('bootstrap-module-domain-public-route' as any, (_app: any, router: an
        * 폴링이 쓰는 길을 그대로 쓴다 — 검증도 유입도 같은 자리다. 그래서 트윈 쪽에서는 물어서 받은
        * 것과 밀어 받은 것이 구별되지 않는다. 구별되는 것은 유입 장부의 `sources` 한 줄뿐이다.
        */
-      ingest: (instanceId, records) => {
-        const { accepted, rejected, masterData } = ingestCanonicalRecords(
-          records as any,
-          domain.id,
-          new Date().toISOString(),
-          TwinEngine.factScope(domain.id, instanceId)
-        )
-        /* 사건이 아닌 것은 상태만 세운다 — 밀어 받는 길도 같은 규율이다(§`applyMasterData`). */
-        if (masterData.length) TwinEngine.applyMasterData(domain.id, instanceId, masterData)
-        const { applied, duplicates } = TwinEngine.ingestLiveResult(domain.id, instanceId, accepted, 'hook')
-        /*
-         * 커널이 받지 못한 수를 이름으로 남긴다 — 트윈이 멈춘 사이 버려진 레코드를 「통과」로 세면
-         * 화면이 100% 라고 말한다. 중복으로 걸러진 것은 버려진 것이 아니므로 빼고 센다.
-         */
-        const undelivered = Math.max(0, accepted.length - applied - duplicates)
-        TwinEngine.recordIngestResult(domain.id, instanceId, records.length, rejected, Date.now(), undelivered)
-        /*
-         * 떨어진 것을 **수가 아니라 목록으로** 넘긴다 — 응답에 실어야 보내는 쪽이 그것만 따로 둘 수
-         * 있다. 수만 주면 배치 전체를 다시 보내거나 전부 버리는 두 갈래밖에 없다.
-         */
-        return { applied, duplicates, rejected }
-      }
+      /*
+       * 유입 몸통은 `live-ingest.ts` 한 곳에 있다 — backfill 이 같은 것을 쓴다. 여기에 두면 두 길이
+       * 서로 다른 규칙으로 받게 되고, 한쪽만 수정되는 날이 온다.
+       */
+      ingest: (instanceId, records) => liveIngest(domain.id, instanceId, records, 'hook'),
+      /*
+       * 구멍을 본 그 자리에서 바로 받는다 — 번호가 비었다는 것을 아는 가장 이른 순간이다.
+       * 기다리지 않는다(§`requestFill`): 훅의 응답이 늦으면 보내는 쪽이 되풀이한다.
+       */
+      onGap: scope => requestFill(domain.id, String(ctx.params.instanceId ?? ''), scope)
     })
     ctx.status = outcome.status
     ctx.body = outcome.body