@things-factory/headless-twin 10.0.15 → 10.0.18

package/server/service/reference/knob-defaults.ts

@@ -5,7 +5,7 @@
  * 템플릿은 노브마다 기본값을 선언한다(`knobs[].default`). 그런데 그 기본값을 채우는 일을 **위자드만**
  * 하고 있었다 — 서버는 받은 파라미터를 그대로 `build(p)` 에 넘긴다. 그래서 파라미터를 일부만 주고
  * 부르면(AI·스크립트·API 호출자) 템플릿 안에서 `Number(p.inboundRate) || 0` 이 **0** 이 되고,
- * 발생률 0 = 도착 없음 = **아무것도 하지 않는 트윈**이 조용히 만들어진다.
+ * 발생률 0 = 도착 없음 = **아무것도 하지 않는 트윈**이 알리지 않고 만들어진다.
  *
  * 실제로 그 함정을 밟았다: 유통가공 창고를 파라미터 일부만 주고 만들었더니 이벤트가 0건이었고,
  * 처음에는 템플릿이 깨진 것으로 오진했다. 기본값을 아는 곳이 계약(노브 스키마)인데 그것을 적용하는
@@ -13,12 +13,12 @@
  *
  * ── 0 을 기본값으로 덮지 않는다 ─────────────────────────────────────────────
  * 발생률 `0` 은 "도착 없음" 이라는 **뜻 있는 값**이다. 없는 것과 0 은 다르다 — falsy 로 판정해 덮으면
- * "자극 없이 구조만 보겠다" 는 선언이 조용히 뒤집힌다. 그래서 **키가 없을 때만** 채운다.
+ * "자극 없이 구조만 보겠다" 는 선언이 알리지 않고 뒤집힌다. 그래서 **키가 없을 때만** 채운다.
  * `null` 은 없는 것으로 본다(JSON·GraphQL 경로에서 "주지 않음" 이 null 로 오는 일이 흔하다).
  *
  * ── 선언 밖 파라미터는 손대지 않는다 ────────────────────────────────────────
  * 템플릿은 노브에 없는 값도 읽는다(예: `geo` 대신 `lat`/`lon` 폴백). 모르는 키를 걷어내면 그 경로가
- * 조용히 끊긴다. 그대로 통과시킨다.
+ * 알리지 않고 끊긴다. 그대로 통과시킨다.
  */
 
 /** 템플릿 노브 — 기본값 적용에 필요한 만큼만 본다. */
@@ -48,7 +48,7 @@ export function applyKnobDefaults(knobs: readonly KnobLike[] | undefined | null,
 /**
  * 기본값으로 채운 노브 이름들 — 호출자에게 "무엇을 내가 정해 줬는지" 알릴 때 쓴다.
  *
- * 조용히 채우는 것도 조용히 비우는 것만큼 위험하다: 사용자가 준 적 없는 값으로 트윈이 만들어졌는데
+ * 알리지 않고 채우는 것도 알리지 않고 비우는 것만큼 위험하다: 사용자가 준 적 없는 값으로 트윈이 만들어졌는데
  * 아무 말이 없으면, 나중에 "왜 이 수치인가" 를 아무도 답할 수 없다.
  */
 export function filledKnobKeys(knobs: readonly KnobLike[] | undefined | null, params: Record<string, unknown> | undefined | null): string[] {

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

@@ -1,5 +1,6 @@
 import type { ReferenceStep } from './reference-progress.js'
 import type { ReferenceMaster } from './reference-master.js'
+import { twinWarn } from '../../engine/log.js'
 
 /*
  * 레퍼런스 어댑터 계약 (reference-management P1) — 정적 마스터 등록(`registerReference`)을
@@ -34,6 +35,27 @@ export interface AdapterConfigField {
   multiline?: boolean // JSON/매핑 등 여러 줄 입력(textarea)
   help?: string // 필드 아래 도움말
   default?: string // 폼 프리필 기본값(예시 매핑/URL 등)
+  /*
+   * 값이 정해진 목록 안에 있을 때 — 화면이 고르게 그린다(타이핑하지 않는다).
+   *
+   * 손으로 적는 칸에 닫힌 값을 받으면 오타가 그대로 저장되고, 그 오타는 오류로 나오지 않는다.
+   * 발전소 종류(`sell` | `self-consumption`)가 그렇다 — 틀리면 계량 방향이 반대가 되는데 어디에도
+   * 표시되지 않는다.
+   *
+   * `label` 은 번역 키를 쓸 수 있다(화면이 `meta()` 로 푼다). `value` 는 저장되는 값이라 번역하지 않는다.
+   */
+  options?: { value: string; label: string }[]
+  /*
+   * 값의 종류가 정해져 있지만 목록이 너무 커서 `options` 로 실을 수 없을 때 — 화면이 그 종류에 맞는
+   * 고르는 칸을 그린다.
+   *
+   *   'timezone'   IANA 시간대. 화면이 `Intl.supportedValuesOf('timeZone')` 로 목록을 만든다.
+   *                400개가 넘고 표준이 갱신되므로 우리가 목록을 들고 있지 않는다.
+   *                이름이 곧 값이자 표시라 번역하지 않는다.
+   *
+   * 자유 입력으로 두면 `Asia/seoul` 같은 오타가 저장되고, 그 오타는 오류로 나오지 않는다.
+   */
+  kind?: 'timezone'
 }
 /** 커넥터 메타데이터 — picker·연결 폼용 표시 정보. */
 export interface AdapterMeta {
@@ -107,10 +129,10 @@ export interface ControlResult {
  * 한 흐름의 읽기 커서 — **어디까지 읽었나.**
  *
  * `since` 와 `seen` 이 **함께** 있어야 한다. 이어 읽기는 경계 시각을 겹쳐 읽고(`gte`), 그 겹침을
- * `seen` 이 걸러 낸다. `gt` 로 좁히면 같은 밀리초의 다른 행이 사라진다 — 조용한 누락이다.
+ * `seen` 이 걸러 낸다. `gt` 로 좁히면 같은 밀리초의 다른 행이 사라진다 — 들어온 것이 없는 누락이다.
  *
  * `seen` 이 예상보다 커지면(한 시각에 몰린 행 수가 늘면) 그것은 원본 쪽 신호다. 어댑터가 그 크기를
- * 말해야 한다 — 조용히 커지게 두면 이어 읽기가 막히는 순간까지 아무도 모른다.
+ * 말해야 한다 — 알리지 않고 커지게 두면 이어 읽기가 막히는 순간까지 아무도 모른다.
  */
 export interface LiveFeedCursor {
   /** 그 흐름에서 마지막으로 본 시각(원본의 시각, ISO). */
@@ -119,6 +141,28 @@ export interface LiveFeedCursor {
   seen: string[]
 }
 
+/**
+ * **트윈이 지금 들고 있는 물품 하나** — 붙는 커넥터가 견줄 근거(§`LiveFeedContinuity.observedItems`).
+ *
+ * 커널 어휘로 낸다. 원본의 낱말(그 시스템의 상태 코드)로 내지 않는 이유가 있다: 원본 낱말은 여러 개가
+ * 커널의 한 값으로 모이므로(예: 네 상태가 「진행 중」 하나가 된다) 되돌릴 수 없다. 그리고 되돌릴
+ * 필요도 없다 — 두 원본 상태가 커널에서 같은 값이면 **트윈이 든 사실은 바뀌지 않았다.**
+ */
+export interface ObservedItemFact {
+  /** 트윈이 든 물품의 키 — 비직렬 재고는 `클래스@자리`. */
+  id: string
+  /** 클래스 식별자(원문). */
+  epcClass?: string
+  location?: string
+  qty?: number
+  uom?: string
+  /** 표준 처분(CBV) — 원본 상태 코드가 아니다. */
+  disposition?: string
+  /** 유통기한(밀리초). */
+  expiry?: number
+  lot?: string
+}
+
 /**
  * 재기동을 넘어 이어지는 읽기 상태 — 참조 계층이 소유하고 어댑터에 건넨다(§`openLiveFeed`).
  *
@@ -127,6 +171,21 @@ export interface LiveFeedCursor {
 export interface LiveFeedContinuity {
   /** 지난번에 어디까지 읽었나 — 없으면 첫 붙음이다(그때만 되돌아볼 날수로 창을 만든다). */
   cursor?: { streams?: Record<string, LiveFeedCursor>; firstAttachedAt?: string }
+  /**
+   * **트윈이 지금 들고 있는 물품** — 붙는 커넥터가 「무엇이 바뀌었나」를 견줄 근거 (2026-08-28).
+   *
+   * ── 무엇을 고치나 ───────────────────────────────────────────────────────────
+   * 전량 절대값을 읽는 커넥터는 지난 주기와 견주어 **바뀐 것만** 낸다. 그 비교 표가 프로세스 안에만
+   * 있어서, 재기동하면 커넥터가 자기 기억을 잃고 **전량을 「바뀐 것」으로 판정**한다. 승화푸드에서 그
+   * 한 번이 2,665건이었고, 재기동마다 지난 기록을 덮었다.
+   *
+   * **트윈은 잃지 않는다** — 저장본에서 되세우고 뜬다(실측 로그: `items 2665 · orders 4794`). 잃는
+   * 쪽은 커넥터다. 그래서 트윈이 아는 것을 건네면 첫 주기부터 바뀐 것만 나간다.
+   *
+   * 없으면 `undefined` 다 — 그것이 「트윈이 아무것도 모른다」는 사실이고, 그때만 전량이 새 사실이다.
+   * 빈 배열로 메우지 않는다(그러면 「모른다」와 「없다」가 같아진다).
+   */
+  observedItems?: ObservedItemFact[]
   /**
    * 커서가 움직였다고 알린다 — 이 층이 저장한다.
    *
@@ -137,11 +196,11 @@ export interface LiveFeedContinuity {
   /**
    * **원본에 닿지 못했다** — 어댑터가 읽기 실패를 알린다(2026-08-23).
    *
-   * ── 무엇이 조용했나 ─────────────────────────────────────────────────────────
+   * ── 무엇이 아무 신호도 내지 않았나 ─────────────────────────────────────────────────────────
    * 실 원본이 끊겼을 때(접속 시간 초과) 트윈의 **조회 가능한 상태 어디에도** 그 사실이 없었다.
    * `onRecords` 가 불리지 않으면 유입 장부에 아무 일도 일어나지 않고, `TwinReference.lastError` 는
    * 마스터 동기·접속 시험에만 적힌다. 그래서 화면이 볼 수 있는 것은 「새 사실이 없다」뿐이었고,
-   * 그것은 **「원본이 조용하다」와 구별되지 않는다.**
+   * 그것은 **「연결된 시스템에서 들어온 것이 없다」와 구별되지 않는다.**
    *
    * 어댑터는 로그로 말하고 있었다(재시도 경고). 그러나 **로그는 사람이 볼 때만 값이 있다** — 화면이
    * 말하려면 상태에 있어야 한다. 이 통로가 그 자리다.
@@ -151,9 +210,35 @@ export interface LiveFeedContinuity {
    * 흐름 여럿을 읽는 원본은 흐름 이름을 함께 준다(어느 표가 막혔나가 원인 찾기의 절반이다).
    *
    * **빈 읽기는 실패가 아니다** — 원본이 「새 것이 없다」고 답한 것은 닿았다는 뜻이므로 `onRecords([])`
-   * 로 알린다. 그 둘을 섞으면 조용한 원본이 끊긴 원본으로 보인다(고치려던 것의 반대 방향으로 틀린다).
+   * 로 알린다. 그 둘을 섞으면 들어온 것이 없는 연결이 끊긴 원본으로 보인다(고치려던 것의 반대 방향으로 틀린다).
+   *
+   * ── 무엇을 어댑터가 보내고 무엇을 이 층이 세나 (2026-08-27) ─────────────────
+   * 어댑터는 **이유**만 보낸다 — 그리고 물러섰다면 다음에 다시 물을 때까지의 시간을 함께 보낸다.
+   *
+   * 연달아 몇 번 실패했는지와 언제부터 실패하고 있는지는 **이 층이 이미 센다**(`recordReadFailure`).
+   * 그것을 어댑터가 함께 보내면 같은 수를 두 곳에서 세게 되고, 갈라지면 어느 쪽이 사실인지 알 수 없다.
+   *
+   * `reason` 에 **완성된 문장을 담지 않는다.** 이 값은 화면에 그려지고, 화면은 다섯 언어로 그린다.
+   * 「3회 연달아 …부터 읽지 못했습니다」처럼 한 언어의 문장을 넣으면 그 문장은 번역되지 않고, 이 층이
+   * 세는 수와 어긋날 수도 있다. 이유 하나만 짧게 준다(접속 시간 초과 · 401 · 형식 오류).
+   */
+  onReadFailure?: (info: {
+    reason: string
+    stream?: string
+    /** 다음에 다시 물을 때까지 남은 시간(ms) — 물러섰을 때만 준다. */
+    nextRetryMs?: number
+  }) => void
+  /**
+   * **끊겼다가 돌아왔다** — 어댑터가 회복을 알린다 (2026-08-27).
+   *
+   * ── 왜 따로 알려야 하나 ─────────────────────────────────────────────────────
+   * 읽기가 다시 성공하면 실패 기록은 지워진다. 그것만 하면 「끊긴 적이 있었다」가 화면에서 사라지고,
+   * 밤새 두 시간 끊겼던 연결과 한 번도 끊기지 않은 연결이 아침에 똑같이 보인다.
+   *
+   * 읽기 성공(`onRecords`)만으로 이 층이 회복을 유추하지 않는다 — 몇 번 실패한 뒤였는지와 얼마나
+   * 끊겨 있었는지는 재시도를 관리하는 어댑터가 안다.
    */
-  onReadFailure?: (info: { reason: string; stream?: string }) => void
+  onRecovered?: (info: { afterFailures: number; downMs: number }) => void
   /**
    * **읽었는데 창을 넘길 수 없다** — 어댑터가 커서 정체를 알린다 (2026-08-24).
    *
@@ -193,7 +278,7 @@ export interface LiveFeedContinuity {
    *
    * **풀리면 부르지 않는 것으로 끝나지 않는다** — 이유가 사라졌으면 `count: 0` 으로 부르는 것이 아니라
    * 그 이유를 더 이상 보내지 않으면 된다… 가 **아니다.** 장부는 마지막 값을 들고 있으므로, 풀린 것을
-   * 알리려면 그 이유로 `count: 0` 을 한 번 보내라(그때 줄이 사라진다). 조용히 그치면 낡은 수가 남는다.
+   * 알리려면 그 이유로 `count: 0` 을 한 번 보내라(그때 줄이 사라진다). 알리지 않고 그치면 낡은 수가 남는다.
    *
    * 이유는 **자유 문자열**이다 — 무엇을 왜 안 받는지는 원본마다 다르고, 계약이 목록을 닫으면 새 원본을
    * 붙일 때마다 계약을 고치게 된다(흐름 열쇠와 같은 규율). 사람이 읽을 문장으로 적어라.
@@ -249,7 +334,7 @@ export interface ReferenceAdapter {
    * 것이 「원본의 사실」이 아니라 「창의 함수」였다.
    *
    * 그런데 미러의 상태는 **원천으로 서야 한다**(같은 절: 「미러의 진실은 원천이다 … 심으면 떠난 물건이
-   * 되살아난다」). 그러니 저널을 접어 상태를 세우는 것으로 고칠 일이 아니다 — 그 선언의 **전제**가
+   * 되살아난다」). 그러니 저널을 계산해 상태를 세우는 것으로 고칠 일이 아니다 — 그 선언의 **전제**가
    * 「원천이 다시 말해 준다」이고, 창이 좁아지면 그 전제가 깨진다. 창을 고치는 것이 그 원칙을 지키는 길이다.
    *
    * ── 계약의 모양 ─────────────────────────────────────────────────────────────
@@ -259,11 +344,31 @@ export interface ReferenceAdapter {
    *    `Set` 을 받으면 이 층이 직렬화를 알게 되고, 커서 모양이 바뀔 때 두 곳을 고친다.
    *  · `firstAttachedAt` — **첫 창을 만든 시각.** 이후 재기동에서 바뀌지 않는다. 커널은 아는 구간의
    *    상한만 안다(`nowTime` = 마지막으로 들은 시각). 이 값이 하한이고, 둘이 「이 트윈이 아는 구간」이다.
-   *    화면이 수를 보일 때 그 구간을 함께 말해야 한다 — 말하지 않으면 조용히 자르는 것이 된다.
+   *    화면이 수를 보일 때 그 구간을 함께 말해야 한다 — 말하지 않으면 알리지 않고 자르는 것이 된다.
    *  · **커서가 없을 때만** 되돌아볼 날수를 쓴다. 그 순간이 `firstAttachedAt` 이다.
    *
    * 주지 않는 호출자와도 함께 선다(선택 인자) — 커서를 모르는 배포는 예전처럼 동작한다.
    */
+  /**
+   * (선택) **연결된 시스템이 밀어 준 것**을 우리 레코드로 옮긴다 — 웹훅.
+   *
+   * ── 왜 `openLiveFeed` 와 나누나 (2026-08-26) ───────────────────────────────
+   * `openLiveFeed` 는 「가져오기」와 「옮기기」를 한 함수에 담고 있다. 그래서 가져오는 방식이 바뀌면
+   * (그쪽이 밀어 주면) 옮기는 코드를 쓸 수 없었다 — 같은 파일 안에 있는데 밖에서 부를 수 없다.
+   *
+   * 이 함수는 **옮기기만** 한다. 밖에서 받은 본문을 받아 우리 레코드 목록을 돌려준다. 입구·인증·유입은
+   * 프레임워크가 맡는다(§`reference-hook`).
+   *
+   * ── 옮길 수 없으면 던진다 ─────────────────────────────────────────────────
+   * 빈 목록과 「옮길 수 없다」는 다르다. 빈 목록은 「우리와 무관한 것이 왔다」이고, 던지는 것은 「그쪽
+   * 모양이 우리가 아는 것과 다르다」다. 그 둘을 같게 답하면 그쪽 모양이 바뀐 것을 아무도 모른다.
+   *
+   * ── 판단은 여기서 한다 ────────────────────────────────────────────────────
+   * 통신이 끊긴 설비의 값을 보내지 않는 것, 잰 시각이 나아가지 않은 줄을 거르는 것 — 폴링에서 하던
+   * 판단을 여기서도 한다. 그래야 두 길이 같은 답을 낸다.
+   */
+  handleInbound?(cfg: ConnectionConfig, site: { siteId: string }, body: unknown, headers: Record<string, unknown>): unknown[]
+
   openLiveFeed?(
     cfg: ConnectionConfig,
     site: SiteDescriptor,
@@ -322,7 +427,7 @@ export interface ReferenceAdapter {
  *   `product`    실 시스템 **여러 배포**에 붙여 확인했다 — 그때 비로소 제품의 성질이라 말할 수 있다.
  *
  * `instance` 와 `product` 를 가르는 이유: 첫 실 연동에서 그 배포만의 성질이 넷 드러났고(관계 리솔버가
- * 다른 테넌트의 행을 답한다 · 모르는 필터를 조용히 무시한다 · 지워진 품목의 BOM 이 남아 있다 ·
+ * 다른 테넌트의 행을 답한다 · 모르는 필터를 알리지 않고 무시한다 · 지워진 품목의 BOM 이 남아 있다 ·
  * 사실상 무한을 뜻하는 표식) **그것이 그 제품의 성질인지 그 인스턴스의 성질인지 아무도 모른다.**
  * 두 번째 배포가 붙는 날 갈린다. 그 사실을 어휘가 담는다.
  */
@@ -378,7 +483,37 @@ export function capabilitiesOf(adapter: ReferenceAdapter | undefined): Reference
 /* 어댑터 "타입" 레지스트리(전역·인메모리) — 레퍼런스 데이터는 DB(TwinReference), 어댑터 동작은 여기. */
 const adapters = new Map<string, ReferenceAdapter>()
 
+/**
+ * 어댑터를 등록한다 — 그리고 **선언과 구현이 어긋나면 그 자리에서 말한다.**
+ *
+ * ── 왜 필요한가 (2026-08-26 실측) ──────────────────────────────────────────
+ * 능력 판정(`capabilitiesOf`)은 **한 방향만** 본다: 선언했는데 구현이 없는 것은 걸러 내고, **구현했는데
+ * 선언이 없는 것은 아무 말도 하지 않는다.** 그래서 다음이 오류 없이 일어난다.
+ *
+ *   커넥터가 `openLiveFeed` 를 구현한다 → `capabilities: ['live']` 를 잊는다
+ *   → 연결 화면이 「이 원본은 라이브를 못 낸다」로 읽는다
+ *   → 재기동 정책을 정할 수 없어 트윈 생성이 거절된다
+ *   → 사람이 보는 것은 「재기동 정책이 없습니다」뿐이다
+ *
+ * 실제로 그렇게 막혔고(태양광 발전소), 원인을 찾는 데 코드를 뒤져야 했다. 지금 저장소에서 같은 상태인
+ * 커넥터가 일곱이다.
+ *
+ * ── 왜 막지 않고 알리기만 하나 ──────────────────────────────────────────────
+ * 등록에서 던지면 커넥터 하나 때문에 호스트가 못 뜬다. 만들다 만 커넥터를 들고 있는 사람이 아무것도
+ * 못 하게 된다. 그리고 이 어긋남은 **고칠 수 있는 것**이지 위험한 것이 아니다 — 말해 주면 된다.
+ */
 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)
+  )
+  if (undeclared.length) {
+    twinWarn(
+      `[reference] connector "${adapter.type}" implements ${undeclared.join(' and ')} but does not declare it — ` +
+        `add capabilities: [${undeclared.map(c => `'${c}'`).join(', ')}] or remove the implementation. ` +
+        'Until then the screens treat this connector as unable to do it, and a live twin cannot be created from it.'
+    )
+  }
   adapters.set(adapter.type, adapter)
 }
 export function getAdapter(type: string): ReferenceAdapter | undefined {

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

@@ -0,0 +1,145 @@
+/*
+ * 연결된 시스템이 **밀어 주는** 사실을 받는 자리 — 웹훅.
+ *
+ * 규약(상태 코드 · 비밀값 · 대상 확인)은 `hook-contract.ts` 에 있다. 여기는 그것을 써서 찾고 · 확인하고 ·
+ * 커넥터에게 옮기게 하고 · 유입으로 넘기는 순서만 맡는다.
+ *
+ * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+ * 지금 모든 커넥터가 주기적으로 물어봅니다(폴링). 그 방식은 두 가지를 치릅니다. 연결된 시스템이 값을
+ * 갱신하는 주기보다 자주 물으면 같은 값을 되풀이 받고, 그쪽 서버에 그만큼 부담을 줍니다. 실제로
+ * 태양광 발전소에 10초마다 물으면서 10분마다 바뀌는 값을 받아 왔습니다.
+ *
+ * 연결된 시스템이 「바뀌었다」를 말해 줄 수 있으면 그것을 받는 것이 낫습니다. 이 파일이 그 입구입니다.
+ *
+ * ── 규약 ────────────────────────────────────────────────────────────────────
+ *
+ *   주소     POST /domain/<도메인>/twin/hook/<연결이름>/<트윈>
+ *   인증     연결 설정에 저장한 비밀값(`hookSecret`)을 헤더로 보낸다
+ *            X-Twin-Hook-Secret: <비밀값>   또는   Authorization: Bearer <비밀값>
+ *   본문     연결된 시스템이 정한 모양 그대로. 우리 어휘로 옮기는 것은 커넥터의 일이다
+ *   응답     아래 §`hookStatus`
+ *
+ * ── 왜 사람 인증(JWT)이 아닌가 ──────────────────────────────────────────────
+ * 밀어 주는 쪽은 사람이 아닙니다. 우리 토큰을 발급받아 갱신하며 관리하라고 요구하면 대부분의 현장에서
+ * 연동이 서지 않습니다. 그래서 연결마다 비밀값을 두고 그것으로 확인합니다.
+ *
+ * **비밀값이 없는 연결은 훅을 받지 않습니다.** 기본이 거부입니다 — 인증 없는 입구를 열어 두는 것보다
+ * 훅을 못 쓰는 것이 낫습니다.
+ *
+ * ── 왜 커넥터가 옮기나 (시나리오가 아니라) ──────────────────────────────────
+ * 연결된 시스템의 웹훅은 그쪽이 정한 고정된 모양으로 옵니다. 그 모양을 아는 것은 그 커넥터이고,
+ * 옮기는 판단은 코드여야 테스트로 지킬 수 있습니다. 실제로 지금 커넥터들이 코드로 판단합니다 —
+ * 통신이 끊긴 설비의 값은 보내지 않고, 잰 시각이 나아가지 않은 줄은 거릅니다. 그 판단을 변환식으로
+ * 옮기면 약해지고 테스트가 없어집니다.
+ *
+ * ── 밀어 주기만으로는 안 된다 ───────────────────────────────────────────────
+ * 훅은 반드시 놓칩니다 — 우리가 내려가 있을 때, 그쪽이 못 보냈을 때, 네트워크가 끊겼을 때. 그래서
+ * 훅을 쓰는 연결도 **드문 폴링을 유지합니다.** 폴링의 역할이 「값을 가져오는 것」에서 「놓친 것이 있나
+ * 확인하는 것」으로 바뀌는 것입니다. 그 주기는 연결 설정이 정합니다.
+ *
+ * ── 같은 것이 두 번 오는 것 ─────────────────────────────────────────────────
+ * 밀어 주는 방식은 재전송이 정상입니다(그쪽이 우리 응답을 못 받으면 다시 보냅니다). 그것은 유입
+ * 경계가 이미 거릅니다(§`FactDeduper`) — 이 파일이 따로 하지 않습니다. 응답에 몇 건이 중복이었는지
+ * 함께 알립니다.
+ */
+import { getRepository } from '@things-factory/shell'
+
+import { TwinReference } from './twin-reference.js'
+import { getAdapter } from './reference-adapter.js'
+import { HOOK_STATUS, producedInstance, secretFromHeaders, secretMatches, type HookOutcome } from './hook-contract.js'
+
+/**
+ * 훅 하나를 처리한다 — 찾고 · 확인하고 · 커넥터에게 옮기게 하고 · 유입으로 넘긴다.
+ *
+ * 유입 자체(`ingest`)는 부르는 쪽이 넘겨 준다: 이 파일이 엔진을 직접 부르면 시험할 때 엔진이 필요해지고,
+ * 그러면 규약을 확인하는 시험을 쓸 수 없다.
+ */
+export async function handleHook(args: {
+  domainId: string
+  source: string
+  instanceId: string
+  headers: Record<string, unknown>
+  body: unknown
+  /** 레코드를 트윈에 넣는다 — 받은 수와 버린 수를 돌려준다. */
+  ingest: (instanceId: string, records: unknown[]) => { applied: number; duplicates: number; rejected: number }
+}): Promise<HookOutcome> {
+  const { domainId, source, instanceId, headers, body, ingest } = args
+
+  const ref = await getRepository(TwinReference)
+    .findOne({ where: { domain: { id: domainId }, source } })
+    .catch(() => null)
+  if (!ref) {
+    return { status: HOOK_STATUS.unknownTarget, body: { ok: false, error: `unknown connection "${source}"` } }
+  }
+
+  const cfg: any = (ref as any).connectionConfig ?? {}
+  const expected = String(cfg.hookSecret ?? '').trim()
+  if (!expected) {
+    /* 비밀값을 선언하지 않은 연결은 훅을 받지 않는다 — 기본이 거부다. */
+    return {
+      status: HOOK_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 site = producedInstance(ref as any, instanceId)
+  if (!site) {
+    return {
+      status: HOOK_STATUS.unknownTarget,
+      body: { ok: false, error: `twin "${instanceId}" was not created by connection "${source}"` }
+    }
+  }
+
+  const adapter: any = getAdapter(String((ref as any).adapterType ?? ''))
+  if (typeof adapter?.handleInbound !== 'function') {
+    return {
+      status: HOOK_STATUS.unsupported,
+      body: { ok: false, error: `connector "${(ref as any).adapterType}" cannot take pushed events (no handleInbound)` }
+    }
+  }
+
+  let records: unknown[]
+  try {
+    records = adapter.handleInbound(cfg, site, body, headers) ?? []
+  } catch (e: any) {
+    /* 옮기지 못한 것은 그쪽 모양이 바뀐 것이다 — 다시 보내도 같으므로 재시도를 부르지 않는다. */
+    return { status: HOOK_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' } }
+  }
+  if (!records.length) {
+    /* 옮길 것이 없는 것은 오류가 아니다 — 그쪽이 우리와 무관한 것을 보낸 것일 수 있다. */
+    return { status: HOOK_STATUS.ok, body: { ok: true, offered: 0, applied: 0, duplicates: 0, rejected: 0 } }
+  }
+
+  let result: { applied: number; duplicates: number; rejected: number }
+  try {
+    result = ingest(instanceId, records)
+  } catch (e: any) {
+    return { status: HOOK_STATUS.failed, body: { ok: false, error: e?.message ?? 'ingest failed' } }
+  }
+
+  if (result.applied === 0 && result.duplicates === 0 && records.length > 0 && result.rejected === 0) {
+    /*
+     * 넣었는데 한 건도 반영되지 않았고 중복도 거부도 아니면, 그 트윈이 실시간으로 돌지 않는 것이다.
+     * 200 을 주면 그쪽은 전달된 줄 알고 그 사실을 버린다. 그래서 재시도로 풀리지 않는다는 것을 코드로
+     * 말한다 — 사람이 트윈을 띄워야 한다.
+     */
+    return {
+      status: HOOK_STATUS.notLive,
+      body: { ok: false, error: `twin "${instanceId}" is not running live — nothing was applied`, offered: records.length }
+    }
+  }
+
+  return {
+    status: HOOK_STATUS.ok,
+    body: { ok: true, offered: records.length, applied: result.applied, duplicates: result.duplicates, rejected: result.rejected }
+  }
+}

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

@@ -1,8 +1,9 @@
 import { twinLog, twinWarn, twinError } from '../../engine/log.js'
 import { getRepository } from '@things-factory/shell'
 
-import { getAdapter, type ConnectionConfig, type LiveFeedContinuity, type SiteDescriptor } from './reference-adapter.js'
-import { TwinEngine, ingestCanonicalRecords, registerLiveFeedProbe, type CanonicalRecord } from '../../engine/index.js'
+import { getAdapter, type ConnectionConfig, type LiveFeedContinuity, type ObservedItemFact, type SiteDescriptor } from './reference-adapter.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'
 
@@ -35,7 +36,7 @@ export async function startReferenceLiveFeed(
    * (`endpoint`·`token`…), `site` 는 커넥터가 원본에서 발견한 것이다 — **레퍼런스의 이름은 호스트가
    * 붙이는 것이고 원본은 그것을 모른다.** 커넥터가 채울 수 없는 값을 커넥터에서 읽으려 한 것이 잘못이었다.
    *
-   * 주지 않으면 커서를 잇지 않고 **그 사실을 말한다**(조용히 창이 미끄러지지 않게).
+   * 주지 않으면 커서를 잇지 않고 **그 사실을 말한다**(알리지 않고 창이 미끄러지지 않게).
    */
   source?: string
 ): Promise<boolean> {
@@ -53,7 +54,7 @@ export async function startReferenceLiveFeed(
   /*
    * **어디까지 읽었나를 이 층이 들고 건넨다**(§`LiveFeedContinuity`, 2026-08-23).
    *
-   * 어댑터가 이 값을 자기 사물함에 두면 원본이 늘 때마다 저장 기제가 늘고, 그중 하나가 조용히 다르게
+   * 어댑터가 이 값을 자기 사물함에 두면 원본이 늘 때마다 저장 기제가 늘고, 그중 하나가 알리지 않고 다르게
    * 동작한다. 그리고 커널이 이미 갈라 두었다: 「원천이 애초에 다시 말해 주지 않는 축」은 재기동
    * 연속성으로 이어받는다(§`hydrateContinuity`) — 읽기 커서가 정확히 그 성질이다.
    *
@@ -61,21 +62,53 @@ export async function startReferenceLiveFeed(
    * 첫 창을 만든다. 빈 객체로 메우지 않는다(그러면 첫 붙음과 이어 붙음이 같아진다).
    */
   const continuity = await loadLiveCursor(domainId, instanceId, source)
+  /*
+   * ── **트윈이 아는 것을 함께 건넨다** (2026-08-28) ───────────────────────────
+   *
+   * 전량 절대값을 읽는 커넥터는 지난 주기와 견주어 바뀐 것만 낸다. 그 비교 표가 프로세스 안에만
+   * 있어서 재기동하면 커넥터가 전량을 「바뀐 것」으로 판정했다 — 승화푸드에서 2,665건이다.
+   *
+   * 트윈은 저장본에서 되세우므로 잃지 않았다. 그래서 그 사실을 건네면 첫 주기부터 바뀐 것만 나간다.
+   * 커널 어휘로 건넨다 — 원본 낱말로 되돌리는 일은 여러 낱말이 한 값으로 모여 불가능하고, 필요도 없다.
+   */
+  if (continuity) continuity.observedItems = observedItemsOf(domainId, instanceId)
   const unsubscribe = adapter.openLiveFeed(cfg, site, (records: unknown[]) => {
     if (!TwinEngine.owns(domainId, instanceId)) {
       stopReferenceLiveFeed(instanceId) // 인스턴스 사라지면 자가 정지(안전망)
       return
     }
     const offered = Array.isArray(records) ? records.length : records ? 1 : 0
-    const { accepted, rejected } = 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) ─────────────────────────
+     *
+     * 마스터데이터 — 변하지 않는 속성(유통기한·로트번호). 시각축이 없는 값이므로 지난 기록에 적지
+     * 않는다(§`applyMasterData`). 이 문이 없던 동안 그 값은 사건에 실려 왔고, 표준이 그것을
+     * 「들어왔다」에만 허용하므로 전량을 읽는 원본은 **들어오지 않은 것을 들어왔다고** 말해야 했다.
+     *
+     * 반영된 건수를 함께 센다 — 라이브로 돌지 않는 트윈은 0 을 내므로, 그 차이가 「바닥에 버려진 수」다.
+     */
+    const masterApplied = masterData.length ? TwinEngine.applyMasterData(domainId, instanceId, masterData) : 0
+    if (masterData.length && masterApplied < masterData.length) {
+      twinWarn(
+        `[twin-live] "${instanceId}": ${masterData.length - masterApplied}/${masterData.length} master data element(s) NOT applied — ` +
+          'the twin is not running live; lot attributes such as expiry will stay empty.'
+      )
+    }
     /*
      * 커널이 **몇 건을 실제로 받았나**를 함께 본다. 트윈이 라이브로 돌지 않으면 `ingestLive` 가 0 을
      * 돌려주고, 그 차이가 곧 「바닥에 버려진 수」다. 이것을 통과로 세면 멈춘 트윈이 100% 로 보인다.
      */
-    const applied = accepted.length ? TwinEngine.ingestLive(domainId, instanceId, accepted) : 0
+    /* 어떤 길로 들어왔는지 함께 적는다 — 화면이 「이 트윈은 무엇을 통해 받나」를 말할 수 있게. */
+    const applied = accepted.length ? TwinEngine.ingestLive(domainId, instanceId, accepted, 'connector') : 0
     const undelivered = accepted.length - applied
     /*
-     * **거부한 것을 조용히 버리지 않는다.** 예전에는 `rejected` 를 받지도 않았다 — 커넥터의 매핑이
+     * **거부한 것을 알리지 않고 버리지 않는다.** 예전에는 `rejected` 를 받지도 않았다 — 커넥터의 매핑이
      * 틀리면 트윈은 「아무 일도 일어나지 않는」 모습이 되고, 로그에도 아무 흔적이 없었다.
      *
      * 그다음 자리였던 「화면까지 나르기」를 이제 채운다. 건마다 브로드캐스팅하지 않고 **집계**한다 — 통과분까지
@@ -84,7 +117,7 @@ export async function startReferenceLiveFeed(
      */
     /*
      * **읽었다는 것 자체가 사실이다** — 빈 읽기도 성공이므로 단절 기록을 지운다(§`onReadFailure`).
-     * 그 둘을 섞으면 조용한 원본이 끊긴 원본으로 보인다.
+     * 그 둘을 섞으면 들어온 것이 없는 연결이 끊긴 원본으로 보인다.
      */
     TwinEngine.clearIngestReadFailure(domainId, instanceId)
     TwinEngine.recordIngestResult(domainId, instanceId, offered, rejected, Date.now(), undelivered)
@@ -104,13 +137,35 @@ export async function startReferenceLiveFeed(
   return true
 }
 
+/**
+ * 트윈이 지금 들고 있는 물품을 커널 어휘로 낸다 — 없으면 `undefined`.
+ *
+ * 상태가 없으면(트윈이 아직 아무것도 모르면) `undefined` 다. 빈 배열로 메우지 않는다 — 「모른다」와
+ * 「하나도 없다」는 다른 사실이고, 커넥터가 그 둘에 다르게 반응해야 한다.
+ */
+function observedItemsOf(domainId: string, instanceId: string): ObservedItemFact[] | undefined {
+  const state = TwinEngine.snapshot(domainId, instanceId)
+  const items = (state as any)?.items
+  if (!Array.isArray(items)) return undefined
+  return items.map((i: any) => ({
+    id: String(i?.subLotId ?? i?.epc ?? ''),
+    ...(i?.gtin ? { epcClass: String(i.gtin) } : {}),
+    ...(i?.location ? { location: String(i.location) } : {}),
+    ...(typeof i?.qty === 'number' ? { qty: i.qty } : {}),
+    ...(i?.uom ? { uom: String(i.uom) } : {}),
+    ...(i?.disposition ? { disposition: String(i.disposition) } : {}),
+    ...(typeof i?.expiry === 'number' ? { expiry: i.expiry } : {}),
+    ...(i?.lot ? { lot: String(i.lot) } : {})
+  })).filter((i: ObservedItemFact) => !!i.id)
+}
+
 /**
  * 그 원본의 읽기 커서를 불러오고, 움직이면 저장하는 통로를 만든다.
  *
  * 커서는 **원본(`TwinReference`)의 것**이지 인스턴스의 것이 아니다 — 한 원본이 여러 인스턴스를 낳고
  * (`scopeSpec.produced`) 읽는 것은 한 번이다. 인스턴스마다 커서를 두면 같은 표를 여러 번 읽는다.
  *
- * 저장 실패는 **삼키지 않고 말한다.** 조용히 실패하면 다음 재기동에서 창이 다시 미끄러지고, 그 손실은
+ * 저장 실패는 **삼키지 않고 말한다.** 오류 없이 실패하면 다음 재기동에서 창이 다시 미끄러지고, 그 손실은
  * 오류 없이 사라진다 — 이 컬럼을 만든 이유가 바로 그것이다.
  */
 async function loadLiveCursor(
@@ -120,7 +175,7 @@ async function loadLiveCursor(
   source?: string
 ): Promise<LiveFeedContinuity | undefined> {
   if (!source) {
-    /* 원본을 가리킬 수 없으면 저장할 자리도 없다 — 그 사실을 말한다(조용히 커서 없이 돌지 않게). */
+    /* 원본을 가리킬 수 없으면 저장할 자리도 없다 — 그 사실을 말한다(알리지 않고 커서 없이 돌지 않게). */
     twinWarn('[twin-live] live cursor not carried — the caller did not say which reference this feed reads from')
     return undefined
   }
@@ -157,13 +212,30 @@ async function loadLiveCursor(
      * 그러니 여기서는 `lastError` 에만 적는다(사람이 목록에서 이유를 볼 수 있게). 「지금 닿나」는
      * `ingestHealth().readFailure` 가 답하고, 성공한 주기가 그것을 지운다.
      */
-    onReadFailure: ({ reason, stream }) => {
-      TwinEngine.recordIngestReadFailure(domainId, instanceId, reason, Date.now(), stream)
+    onReadFailure: ({ reason, stream, nextRetryMs }) => {
+      TwinEngine.recordIngestReadFailure(domainId, instanceId, reason, Date.now(), stream, nextRetryMs)
       twinWarn(`[twin-live] "${source}": cannot read from the source${stream ? ` (${stream})` : ''} — ${reason}`)
       repo
         .update({ id: row.id }, { lastError: `live: ${reason}` } as any)
         .catch(err => twinWarn(`[twin-live] "${source}": read failure not recorded — ${err?.message ?? err}`))
     },
+    /*
+     * **끊겼다가 돌아왔다** — 그 사실을 장부에 남긴다 (2026-08-27).
+     *
+     * 실패 기록을 지우기만 하면 「끊긴 적이 있었다」가 화면에서 사라진다. 그러면 밤새 두 시간 끊겼던
+     * 연결과 한 번도 끊기지 않은 연결이 아침에 똑같이 보인다.
+     *
+     * `lastError` 도 함께 지운다 — 목록에 남은 옛 이유가 지금의 상태로 읽힌다.
+     */
+    onRecovered: ({ afterFailures, downMs }) => {
+      TwinEngine.recordIngestRecovered(domainId, instanceId, afterFailures, downMs, Date.now())
+      twinLog(
+        `[twin-live] "${source}": reading again after ${afterFailures} failed attempt(s) — it was out for ${Math.round(downMs / 1000)}s`
+      )
+      repo
+        .update({ id: row.id }, { lastError: null } as any)
+        .catch(err => twinWarn(`[twin-live] "${source}": recovery not recorded — ${err?.message ?? err}`))
+    },
     /**
      * **읽었는데 창을 넘길 수 없다** — 위와 조치가 반대인 사실이다 (2026-08-24).
      *
@@ -222,7 +294,7 @@ export function listReferenceLiveFeeds(): string[] {
 /**
  * 부팅 때 **끊어진 피드를 다시 붙인다** — 도는 미러 트윈에 계측이 계속 들어오게.
  *
- * ── 무엇이 조용히 끊겼나 (2026-08-14) ───────────────────────────────────────
+ * ── 무엇이 알리지 않고 끊겼나 (2026-08-14) ───────────────────────────────────────
  * `startReferenceLiveFeed` 를 부르는 곳은 `importTwinReference` **하나뿐**이었다. 그래서 서버를 한 번
  * 재기동하면 미러 트윈은 「도는 중」이라 말하면서 아무 계측도 받지 않았다 — 오류도 로그도 없이,
  * 사람은 「값이 안 변하네」로 알게 된다. 실 배포에서 재기동 한 번에 계측이 멈추는 셈이다.
@@ -246,7 +318,7 @@ export async function resumeReferenceLiveFeeds(): Promise<{ resumed: string[]; f
    * 다시 세우므로(`startLive`) **먼저 쌓인 수요 구간이 리셋된다** — 실제로 그렇게 났다
    * (로그: `reattached 2 feed(s): ems-plant-1, ems-plant-1`).
    *
-   * 그러니 한 번만 붙이고, **두 레퍼런스가 같은 트윈을 주장한다는 사실은 말한다** — 조용히 하나를
+   * 그러니 한 번만 붙이고, **두 레퍼런스가 같은 트윈을 주장한다는 사실은 말한다** — 알리지 않고 하나를
    * 고르면 어느 접속이 그 트윈을 먹이고 있는지 아무도 모르게 된다.
    */
   const attached = new Map<string, string>() // instanceId → 먼저 붙인 레퍼런스
@@ -308,7 +380,7 @@ export async function resumeReferenceLiveFeeds(): Promise<{ resumed: string[]; f
   }
 
   if (resumed.length) twinLog(`[twin-live] reattached ${resumed.length} feed(s): ${resumed.join(', ')}`)
-  /* **조용히 넘기지 않는다** — 붙지 않은 미러는 「도는데 아무것도 오지 않는」 트윈이다. */
+  /* **알리지 않고 넘기지 않는다** — 붙지 않은 미러는 「도는데 아무것도 오지 않는」 트윈이다. */
   for (const f of failed) twinWarn(`[twin-live] "${f.instanceId}" feed NOT reattached — ${f.error}`)
   return { resumed, failed }
 }