@things-factory/headless-twin 10.0.19 → 10.1.0

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

@@ -42,18 +42,38 @@
  * 경계가 이미 거릅니다(§`FactDeduper`) — 이 파일이 따로 하지 않습니다. 응답에 몇 건이 중복이었는지
  * 함께 알립니다.
  */
+/*
+ * `WebhookResponse` comes from the root, not from `@operato/ops-contract/webhook`.
+ *
+ * That subpath resolves to `webhook-signature`, which is a separate module kept out of the barrel
+ * because it pulls in `node:crypto`. The module actually named `webhook.ts` — status codes, the
+ * envelope, the response — reaches consumers through the root barrel. Importing the response type
+ * from the subpath fails with TS2305, which is what happened here first.
+ */
+import { checkSequence, type WebhookResponse } from '@operato/ops-contract'
 import { WEBHOOK_HEADER, verifyWebhookSignature } from '@operato/ops-contract/webhook'
 
+/*
+ * The body is typed by the contract, not by this file (2026-09-07).
+ *
+ * It was `Record<string, unknown>`, which accepts anything — so nothing checked that what we reply
+ * with is what a sender was told to expect. It was not: the contract declared `rejected` in prose
+ * only, operato-plant guessed "a list of envelope ids", and a whole batch was stamped delivered
+ * while one envelope never landed (mes_outbox_events seq 178 — SENT, attempts 0, no error).
+ *
+ * With `WebhookResponse` here, adding a field to a reply without declaring it fails the build on
+ * this side, which is the side that would otherwise ship the surprise.
+ */
 /** 훅 요청의 결과 — 상태 코드와 본문을 함께 정한다(부르는 쪽이 그대로 답한다). */
 export interface HookOutcome {
   status: number
-  body: Record<string, unknown>
+  body: WebhookResponse
 }
 
 /**
  * 응답 코드 규약 — **계약이 정하고 여기서는 그것을 쓴다**(2026-08-31).
  *
- * 예전에는 이 표가 여기 있었고 보내는 쪽(operato-mes)에 또 있었다. 그래서 같은 409 를 양쪽이 다른
+ * 예전에는 이 표가 여기 있었고 보내는 쪽(operato-plant)에 또 있었다. 그래서 같은 409 를 양쪽이 다른
  * 뜻으로 썼다 — 여기서는 「그 트윈이 실시간으로 돌지 않는다」, 저쪽에서는 「번호가 비었다」였다.
  * 붙였다면 트윈이 안 도는 동안 보내는 쪽이 같은 구간을 계속 다시 보냈다.
  *
@@ -90,7 +110,7 @@ export function secretMatches(given: string, expected: string): boolean {
  * 인증 — **서명이 왔으면 서명을 보고, 아니면 비밀값을 본다.**
  *
  * 두 방식을 두는 이유는 밀어 주는 쪽의 사정이 다르기 때문이다. 이미 붙어 있는 커넥터는 비밀값을 헤더에
- * 싣는 방식으로 만들어졌고, 새로 만드는 것(operato-mes)은 서명을 쓴다. 서명 쪽이 낫다 — 비밀값을 그대로
+ * 싣는 방식으로 만들어졌고, 새로 만드는 것(operato-plant)은 서명을 쓴다. 서명 쪽이 낫다 — 비밀값을 그대로
  * 싣는 방식은 그 요청을 그대로 다시 보내는 것을 막지 못한다.
  *
  * **서명이 왔는데 확인할 수 없으면 거절한다.** 받은 바이트를 들고 있지 않으면(`rawBody` 가 없으면)
@@ -165,13 +185,173 @@ export function seqOf(cursor: unknown, scope: string): number | undefined {
 }
 
 /** 그 단위의 번호만 바꾼 커서를 만든다 — 다른 흐름과 `since`·`seen` 은 그대로 둔다. */
-export function withSeq(cursor: unknown, scope: string, seq: number): Record<string, unknown> {
+export function withSeq(cursor: unknown, scope: string, seq: number, firstSeq?: number): Record<string, unknown> {
   const base = (cursor && typeof cursor === 'object' ? (cursor as Record<string, unknown>) : {}) as Record<string, any>
   const streams = base.streams && typeof base.streams === 'object' ? { ...base.streams } : {}
-  streams[scope] = { ...(streams[scope] ?? {}), seq }
+  const prev = streams[scope] ?? {}
+  /*
+   * **`firstSeq` 는 한 번만 적힌다.** 이 연결이 이 단위를 몇 번부터 받기 시작했는지는 바뀌지 않는
+   * 사실이고, 나중에 덮으면 「앞이 비었나」를 다시 물을 수 없다.
+   *
+   * 그래서 첫 봉투 판정이 있을 때만 넘어온다(`SequencedTake.firstSeq`). 커서가 이미 나아간 뒤에
+   * 이 값을 만들면 그 번호는 첫 번호가 아니라 그때 마침 온 번호다.
+   */
+  streams[scope] = { ...prev, seq, ...(firstSeq !== undefined && prev.firstSeq === undefined ? { firstSeq } : {}) }
   return { ...base, streams }
 }
 
+/**
+ * 이 연결이 이 단위를 **몇 번부터 받기 시작했나** — 적힌 적이 없으면 `undefined`.
+ *
+ * 「앞이 비었나」를 답하려면 이 값이 있어야 한다. 없으면 **모른다고 말해야 한다** — 0 으로 답하면
+ * 1번부터 다 받은 것으로 읽힌다.
+ */
+export function firstSeqOf(cursor: unknown, scope: string): number | undefined {
+  const seq = (cursor as any)?.streams?.[scope]?.firstSeq
+  return typeof seq === 'number' && Number.isInteger(seq) ? seq : undefined
+}
+
+/**
+ * **번호대로 받을 수 있는 데까지 자른다** — 밀어 받는 길과 backfill 하는 길이 이 함수 하나를 지난다.
+ *
+ * ── 왜 갈라 두나 (2026-08-31) ────────────────────────────────────────────
+ * 이 판정이 훅 안에 박혀 있었다. backfill(`fetchSince`)이 같은 판정을 해야 하는데, 거기서 다시 만들면
+ * **두 길이 다른 규칙으로 받는다** — 한쪽만 고쳐지는 날이 오고, 어긋난 그 길에서만 사실이 사라진다.
+ *
+ * 번호 확인을 커넥터가 아니라 프레임워크로 가져온 것과 같은 이유다. 자리가 하나여야 한다.
+ *
+ * ── 첫 구멍에서 멈춘다 ───────────────────────────────────────────────────
+ * 구멍 뒤의 봉투를 받아들이면 그 구멍이 영영 메워지지 않는다. 보내는 쪽은 `expectedSeq` 부터 다시
+ * 보내고, 뒤엣것은 그때 함께 온다.
+ */
+export interface SequencedTake {
+  /** 받아들인 레코드 — 구멍 앞까지다. */
+  records: unknown[]
+  /** 번호를 확인했나. 번호를 매기지 않는 원본은 거짓이고, 그 사실을 응답에 남긴다. */
+  numbered: boolean
+  /** 커서에 적을 번호 — 받은 것이 없으면 없다. */
+  advancedSeq?: number
+  /** 구멍이 났다 — 그 앞부터 다시 받아야 한다. */
+  gap?: { expectedSeq: number; lastSeq: number }
+  /**
+   * 이 단위의 **첫 봉투였다** — 그 앞으로 몇 개를 못 봤나.
+   *
+   * ── 왜 이 칸이 생겼나 (2026-09-06 실측) ──────────────────────────────────
+   * plant 아웃박스의 1~20 이 400 으로 거절돼 그 연결에 커서가 없었다. 다음에 온 21번이 첫 봉투로
+   * 앉으며 **커서가 21 로 뛰었다.** 커서가 0 이었다면 같은 21이 구멍이었다.
+   *
+   * 스무 건이 없는데 구멍으로도 안 세어지고, 경고도 없고, backfill 대상도 아니었다 — backfill 은 커서부터
+   * 묻는다. 그 사실이 아무 데도 안 남았다.
+   *
+   * **손실이라고 말하지 않는다.** 원본이 오래 돌고 있는데 트윈을 나중에 붙이면 그 아래는 애초에
+   * 안 받기로 한 것이다. 계약은 둘을 구별할 수 없으므로 수만 낸다.
+   *
+   * 0 이면 1번부터 시작한 것이라 이 칸을 내지 않는다 — 말할 것이 없다.
+   */
+  firstUnseenBefore?: number
+  /**
+   * 이 묶음의 첫 봉투가 **이 단위의 첫 봉투였다** — 그 번호.
+   *
+   * `firstUnseenBefore` 와 다르다: 이쪽은 1번부터 시작한 연결에도 있다(값 1). 커서에 적어 두면
+   * 나중에 「앞이 비었나」를 답할 수 있다.
+   */
+  firstSeq?: number
+  /**
+   * 이 묶음에서 **가장 낮게 받아들인 번호** — 하나도 못 받았으면 없다.
+   *
+   * `firstSeq` 와 다르다. `firstSeq` 는 「이 단위의 첫 봉투였다」일 때만 있고, 이쪽은 언제나 있다.
+   *
+   * 밑에서부터 다시 받을 때 이것이 필요하다. `from: 0` 으로 부르면 커서가 0 이므로 seq 1 은
+   * `next` 판정이고 `firstSeq` 가 안 생긴다 — 그런데 우리는 실제로 1번부터 갖게 된다. 그 사실을
+   * 적어야 「앞이 비었나」에 답할 수 있다.
+   */
+  lowestSeq?: number
+  /**
+   * 받을 수 없는 묶음 — 그 이유.
+   *
+   * 번호가 있는 봉투와 없는 봉투가 섞였거나 번호가 정수가 아니다. 둘 다 보내는 쪽의 결함이고,
+   * **반쯤 확인한 것을 확인했다고 말하지 않는다.**
+   */
+  refused?: string
+}
+
+export function takeInSequence(args: {
+  items: { record: unknown; seq?: number; at?: string }[]
+  scope?: string
+  /** 이 단위에서 마지막으로 받아들인 번호. 받은 적이 없으면 `undefined`. */
+  lastSeq?: number
+}): SequencedTake {
+  const { items, scope, lastSeq } = args
+
+  const withSeq = items.filter(i => typeof i?.seq === 'number').length
+  if (withSeq && withSeq !== items.length) {
+    return { records: [], numbered: false, refused: `mixed batch — ${withSeq} of ${items.length} items carry a sequence number` }
+  }
+  const numbered = withSeq > 0 && !!scope
+
+  if (!numbered) return { records: items.map(i => i.record), numbered: false }
+
+  let cursor = lastSeq
+  let take = 0
+  let gap: { expectedSeq: number; lastSeq: number } | undefined
+  /* 첫 봉투가 몇 번부터 시작했나 — 그 앞을 못 본 사실을 응답에 남긴다. */
+  let firstUnseenBefore: number | undefined
+  /* 이 단위를 몇 번부터 받기 시작했나 — 커서에 적어 두면 「앞이 비었나」를 나중에 답할 수 있다. */
+  let firstSeq: number | undefined
+  /* 이 묶음에서 가장 낮게 받아들인 번호 — 밑에서부터 다시 받을 때 이것이 firstSeq 가 된다. */
+  let lowestSeq: number | undefined
+  for (const item of items) {
+    let verdict
+    try {
+      verdict = checkSequence(cursor, item.seq as number)
+    } catch (e: any) {
+      return { records: [], numbered: true, refused: e?.message ?? 'bad sequence number' }
+    }
+    if (verdict.kind === 'gap') {
+      gap = { expectedSeq: verdict.expectedSeq, lastSeq: verdict.lastSeq }
+      break
+    }
+    if (verdict.kind === 'first') {
+      firstSeq = item.seq as number
+      /*
+       * 계약이 `unseenBefore` 를 내면 그것을 쓴다. 설치된 판이 그보다 오래됐으면 번호에서 센다 —
+       * 첫 봉투의 번호 아래로 그만큼이 있고 우리는 그것을 받은 적이 없다.
+       *
+       * ⚠ 이 두 번째 길은 계약 0.9.9 가 깔리면 지운다. 그때까지 두는 이유는, 계약을 기다리며
+       * 비워 두면 **코드는 있는데 아무 일도 안 하는 상태**가 되고 그것이 이 결함의 원인과 같은
+       * 모양이기 때문이다.
+       */
+      const unseen = (verdict as any).unseenBefore ?? (item.seq as number) - 1
+      if (unseen > 0) firstUnseenBefore = unseen
+    }
+    if (lowestSeq === undefined) lowestSeq = item.seq as number
+    cursor = verdict.lastSeq
+    take++
+  }
+
+  return {
+    /*
+     * **봉투의 시각을 레코드에 얹는다** — 레코드가 자기 시각을 말하면 그것이 이긴다.
+     *
+     * 시각을 안 싣는 레코드는 ingest 시각으로 떨어지고, 그 값이 실행할 때마다 달라서 fact identity 가
+     * 매번 바뀐다. 그래서 같은 사실을 다시 받으면 dedupe 가 안 되고 새 사실로 앉는다 —
+     * `fillTwinScope` 를 두 번 돌렸더니 저널이 40 → 69건이 됐다(2026-09-06 측정).
+     */
+    records: items.slice(0, take).map(i => {
+      const r = i.record as any
+      if (!i.at || r == null || typeof r !== 'object') return i.record
+      return r.at === undefined && r.eventTime === undefined ? { ...r, at: i.at } : i.record
+    }),
+    numbered: true,
+    /* 앞의 것을 하나도 못 받았으면 커서를 올릴 것이 없다. */
+    ...(take > 0 && typeof cursor === 'number' ? { advancedSeq: cursor } : {}),
+    ...(gap ? { gap } : {}),
+    ...(firstUnseenBefore ? { firstUnseenBefore } : {}),
+    ...(firstSeq !== undefined ? { firstSeq } : {}),
+    ...(lowestSeq !== undefined ? { lowestSeq } : {})
+  }
+}
+
 /** 이 연결이 이 트윈을 만들었나 — 남의 트윈에 밀어 넣지 못하게. */
 export function producedInstance(ref: { scopeSpec?: any } | null | undefined, instanceId: string): { siteId: string } | undefined {
   const produced: any[] = (ref?.scopeSpec as any)?.produced ?? []

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

@@ -0,0 +1,53 @@
+/*
+ * 떨어진 것을 **보내는 쪽이 알아들을 모양으로** 바꾼다 — 순수 판정, 한 곳.
+ *
+ * ── 무엇이 있었나 (2026-09-07 측정) ─────────────────────────────────────────
+ * 훅 응답의 떨어진 목록이 `{ record, errors }` 였고, plant 은 그것을 **봉투 id 문자열 목록**으로
+ * 읽고 있었다.
+ *
+ * ```
+ * headless-twin  rejected: { record, errors }[]        객체 배열
+ * plant          "rejected is a list of envelope ids"  문자열 배열
+ * ```
+ *
+ * `Array.isArray` 는 통과하므로 그쪽의 새 guard 도 안 걸렸다. id 를 맞추는데 객체라 하나도 안 맞고
+ * **묶음 전체가 「보냈음」으로 찍혔다.** 422 와 `ok: false` 를 보냈는데 그쪽 행은 재시도 0 ·
+ * 오류 없음 · 보냈음이었다. 인티그레이션 레인이 두 파일을 나란히 읽어서 찾았다.
+ *
+ * 우리가 말했는데 상대가 못 알아듣는 모양이면, 말한 것이 아니다.
+ *
+ * ── 왜 배선에서 갈라 놓나 ───────────────────────────────────────────────────
+ * `reference-hook.ts` 는 엔티티를 물어서 시험 러너가 못 읽는다. 이 판정은 평범한 값으로 확인할 수
+ * 있어야 하고, 오늘 이 저장소에서 「고쳐도 통과하고 안 고쳐도 통과하는 시험」이 여럿 나왔다.
+ */
+
+/** 훅 응답에 실리는 떨어진 것 하나 — 봉투 id 를 알면 그것을, 모르면 레코드를. */
+export type RejectedForCaller = { eventId: string; errors: string[] } | { record: unknown; errors: string[] }
+
+/**
+ * 떨어진 것에 봉투 id 를 붙인다.
+ *
+ * **짝은 객체 동일성으로 짓는다.** 유입에 넘긴 레코드가 배치의 원소 그대로이므로(§`takeInSequence`)
+ * 커넥터를 고치지 않고도 봉투로 되짚을 수 있다. 값으로 비교하면 같은 모양의 레코드 둘이 서로의 id 를
+ * 가져간다 — 그러면 보내는 쪽이 **엉뚱한 행**을 떨어진 것으로 표시한다.
+ *
+ * **id 를 못 찾으면 레코드를 그대로 싣는다.** 빈 id 를 실으면 보내는 쪽이 아무 행도 못 찾으면서
+ * 「알았다」고 여긴다 — 지금 났던 일이 정확히 그것이다.
+ */
+export function rejectedForCaller(
+  rejected: readonly { record: unknown; errors: string[] }[],
+  items: readonly { record?: unknown; eventId?: unknown }[]
+): RejectedForCaller[] {
+  const idOf = new Map<unknown, string>()
+
+  for (const it of items) {
+    const id = typeof it?.eventId === 'string' && it.eventId.trim() ? it.eventId : undefined
+    if (id && it?.record !== undefined) idOf.set(it.record, id)
+  }
+
+  return rejected.map(r => {
+    const eventId = idOf.get(r.record)
+
+    return eventId ? { eventId, errors: r.errors } : { record: r.record, errors: r.errors }
+  })
+}

package/server/service/reference/index.ts

@@ -1,11 +1,15 @@
+import { ConnectionPortabilityResolver } from './connection-portability-resolver.js'
 import { TwinReferenceResolver } from './reference-resolver.js'
 import { TwinReferenceProgressSubscription } from './reference-progress-subscription.js'
 import { TwinReference } from './twin-reference.js'
 
 export const entities = [TwinReference]
-export const resolvers = [TwinReferenceResolver, TwinReferenceProgressSubscription]
+export const resolvers = [TwinReferenceResolver, TwinReferenceProgressSubscription, ConnectionPortabilityResolver]
 export * from './control-routing.js'
 /* 진행 단계 어휘 — **모든 커넥터가 같은 낱말로 말한다.** 화면은 단계마다 번역 하나만 두면 된다. */
 export * from './reference-progress.js'
 /* 커넥터 점검 하네스 — 실 원본에 붙여 무엇이 채워지고 무엇이 비는지 센다(앱을 띄우지 않는다). */
 export * from './reference-probe.js'
+/* 놓친 구간을 backfill 해 채우는 길 — 밀어 받는 길과 같은 번호 검사를 지난다. */
+export * from './reference-fill.js'
+export * from './connection-portability.js'

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

@@ -0,0 +1,129 @@
+/*
+ * **원천이 축마다 언제·얼마나 자주 내놓나** — 유입 건강이 이 선언으로 견준다.
+ *
+ * ── 왜 필요한가 (2026-09-04 실측) ──────────────────────────────────────────
+ * 유입 건강이 **한 자로 전부를 쟀다.** 10분 안에 아무것도 오지 않으면 「유입 없음」이다. 그런데
+ * 원천마다 시간의 결이 다르다.
+ *
+ *   태양광 발전        일몰에 멈춘다 — 두 사이트가 같은 분 19:25 에 함께
+ *   부하 계측          밤에도 온다 · 15분마다
+ *   인증서 가격        화·목만 거래된다 · 그 날 하루 한 번
+ *   MES · 주방        현장 근무시간 밖에는 사실이 안 난다 · 훅이라 「보내면 온다」
+ *
+ * 그래서 **정상인데 매일 밤 절반이 빨갛게 났다.** 거짓 빨강이 쌓이면 진짜 빨강도 같이 안 읽힌다.
+ *
+ * ── 두 축이고 서로 다르다 ───────────────────────────────────────────────────
+ *   window            지금이 그 축의 활동 시각인가        → 아니면 조용한 것이 정상
+ *   expectedSilenceMs 활동 시각 안에서 이만큼 조용해도 정상 → 넘기면 유입 없음
+ *
+ * 주기를 넘겼어도 활동 시각 밖이면 정상이다. 한 값으로 접을 수 없다 — 인증서 가격이 그 증거다.
+ * 「매일 와야 한다」로 재면 주 5일 중 3일이 빨갛고, 「주 2회」로 재면 이어 쓴 날을 못 본다.
+ *
+ * ── 커널이 일출·일몰을 계산하지 않는다 ─────────────────────────────────────
+ * 굴절·고위도·박명 정의가 다 선택이고, 우리가 정하면 그 순간 방언이다. 그리고 계약이 같은 문제에
+ * 이미 답해 뒀다(§`TwinModelDef.utcOffsetMinutes`): 「긴 지평선의 정확한 답은 호스트가 표준대로
+ * **절대 구간**을 계산해 넣는 것이다」.
+ *
+ * 그래서 원천은 `windowKind: 'daylight'` 로 **종류만** 선언하고, 좌표를 아는 호스트가 날마다
+ * 구체적인 구간을 채운다. **고정 시각을 선언에 박지 않는다** — 일몰 19:25 는 오늘 잰 값이고 두 달
+ * 뒤에는 틀리다. 그것을 박으면 겨울마다 거짓 빨강이 다시 난다.
+ *
+ * ── 「주기 없음」과 「모른다」는 다르다 ──────────────────────────────────────
+ * MES 는 훅으로 밀어 준다 — 몇 분마다가 아니라 「보내면 온다」다. 보낼 것이 없으면 안 보내는 것이
+ * 정상이고, 그것을 침묵으로 판정하면 안 된다.
+ *
+ * 선언하지 않은 축은 **지금까지처럼** 창 하나로 견준다(옛 거동). 「모른다」를 「안 와도 된다」로
+ * 접지 않는다 — 그러면 정말 끊긴 원천이 통째로 조용해진다.
+ */
+import type { WorkCalendarEntry } from '@operato/ops-contract'
+
+/**
+ * 창의 종류 — **호스트가 채워야 하는 것**만 이름이 있다.
+ *
+ * 지금은 하나다. 늘리기 전에 「호스트가 그것을 계산할 근거를 갖고 있나」를 먼저 물어야 한다 —
+ * 좌표 없이 `daylight` 를 선언하면 호스트가 채울 것이 없고, 그러면 그 축은 창이 없는 것과 같다.
+ */
+export type LiveWindowKind = 'daylight'
+
+/** 한 축의 시간성 — 어느 사실이 언제·얼마나 자주 오나. */
+export interface LiveCadence {
+  /**
+   * 어느 축인가 — **`OP_EVENT` 의 값 그대로**(`equipment.status` · `quality.output` …).
+   *
+   * 새 낱말을 만들지 않는다. 만들면 커넥터가 부르는 이름과 장부가 세는 이름이 갈리고, 그때
+   * 선언이 조용히 아무 축에도 안 붙는다.
+   */
+  axis: string
+  /**
+   * 활동 시각 안에서 **이만큼 조용해도 정상**(ms). 없으면 창 하나로 견준다.
+   *
+   * 15분마다 긷는 원천은 이 값을 선언해야 한다 — 안 하면 긷는 사이마다 「유입 없음」으로 보인다.
+   */
+  expectedSilenceMs?: number
+  /**
+   * 이 축이 **활동하는 창** — 근무 달력 어휘 그대로(요일·시간대·휴일).
+   *
+   * 계약이 이미 그 셋을 표현한다. 새 모양을 만들지 않는 이유는 판정하는 함수가 이미 하나
+   * 있기 때문이다(`inWorkCalendar`) — 두 벌이면 화면과 커널이 다른 답을 낸다.
+   */
+  window?: readonly WorkCalendarEntry[]
+  /**
+   * 창을 **호스트가 채우는 종류** — 좌표·표준으로 계산해야 하는 것.
+   *
+   * `window` 와 함께 선언하면 호스트가 채운 것이 이긴다(계산이 선언보다 그 날에 맞다).
+   */
+  windowKind?: LiveWindowKind
+  /**
+   * **보내면 온다** — 이 축은 침묵으로 판정하지 않는다(훅·구독).
+   *
+   * 「주기가 없다」와 「모른다」를 가르는 값이다. 훅은 보낼 것이 없으면 안 보내고, 그것이 정상이다.
+   */
+  pushed?: boolean
+}
+
+/** 그 축의 선언을 찾는다 — 없으면 `undefined`(옛 거동으로 견준다). */
+export function cadenceOf(cadences: readonly LiveCadence[] | undefined, axis: string): LiveCadence | undefined {
+  return cadences?.find(c => c.axis === axis)
+}
+
+/**
+ * 유입 건강이 이 축을 어떻게 견줄 것인가 — **판정에 넘길 두 값으로 옮긴다.**
+ *
+ * `syncVerdictOf` 가 받는 모양(§`ingest-health.ts`)에 맞춘다. 그 함수는 순수하고 달력을 보지
+ * 않으므로, 창 판정은 여기서 끝내고 참·거짓만 넘긴다 — `capabilityOf` 가 `requiredTests` 를 받는
+ * 것과 같은 규율이다.
+ *
+ * ── 「보내면 온다」는 침묵으로 판정하지 않는다 ──────────────────────────────
+ * `pushed` 면 `quietNow` 를 늘 참으로 낸다. 그러면 침묵이 「유입 없음」이 되지 않는다. **다른
+ * 갈래는 그대로 산다** — 버려지는 중·결선 없음은 몇 시든 문제이고 그것들이 이 값보다 앞선다.
+ *
+ * ── 모르면 아무것도 답하지 않는다 ──────────────────────────────────────────
+ * 선언이 없으면 둘 다 비운다. 그때 판정은 지금까지처럼 창 하나로 견준다 — 「모른다」를 「안 와도
+ * 된다」로 접으면 정말 끊긴 원천이 통째로 조용해진다.
+ */
+export function ingestExpectation(
+  cadence: LiveCadence | undefined,
+  ctx: { nowMs: number; utcOffsetMinutes?: number; inWindow?: (window: readonly WorkCalendarEntry[]) => boolean }
+): { expectedSilenceMs?: number; quietNow?: boolean } {
+  if (!cadence) return {}
+
+  const out: { expectedSilenceMs?: number; quietNow?: boolean } = {}
+
+  if (typeof cadence.expectedSilenceMs === 'number' && cadence.expectedSilenceMs > 0) {
+    out.expectedSilenceMs = cadence.expectedSilenceMs
+  }
+
+  if (cadence.pushed) {
+    /* 보낼 것이 없으면 안 보내는 것이 정상이다 — 침묵을 근거로 삼지 않는다. */
+    out.quietNow = true
+    return out
+  }
+
+  /*
+   * 창이 있으면 그것으로 판정한다. **판정할 수단을 안 받았으면 답하지 않는다** — 부르는 쪽이
+   * 달력 판정 함수를 주지 않았는데 우리가 「활동 시각이다」로 단언하면 그것이 지어낸 값이다.
+   */
+  if (cadence.window?.length && ctx.inWindow) out.quietNow = !ctx.inWindow(cadence.window)
+
+  return out
+}

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

@@ -0,0 +1,56 @@
+/*
+ * What a live feed takes its task lease under — pure naming, one place.
+ *
+ * ── Why the name is built here and not by the adapter ──────────────────────
+ * `TaskLease` deliberately has no domain column: the thing 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 its name so the unique index keeps meaning what it says.
+ *
+ * An adapter cannot honour that. It receives `cfg` and `site`, and neither
+ * carries a domain — so a name built from `siteId` would let two domains that
+ * happen to share a plant code block each other's channel. It would look
+ * exactly like "someone else holds it", which is the ordinary case on every
+ * instance but one, so nothing would be logged and nothing would look wrong.
+ *
+ * ── Why the source and not the site ───────────────────────────────────────
+ * One reference is one connection to one system, and that connection is what a
+ * second instance must not open twice. A source that discovers several sites
+ * still reads them over that one connection.
+ *
+ * ── Why the parts are joined with `::` ────────────────────────────────────
+ * The same separator the push cursor key already uses (`instanceId::scope`), so
+ * a person reading `task_leases` during an incident sees the same shape they
+ * see in `liveCursor`.
+ */
+
+/** Marks the name as a live feed, so a lease table read tells you what kind of task it is. */
+const PREFIX = 'twin-live'
+
+/**
+ * The lease name for one twin's feed.
+ *
+ * ── Domain and instance are required; the source is not ───────────────────
+ * A feed is registered per instance, so domain plus instance already names it
+ * uniquely. The source is appended when known because it is what a person
+ * reading `task_leases` wants to see — which system this channel talks to.
+ *
+ * Missing a domain or an instance is refused rather than filled in. A blank
+ * there would collapse two different feeds onto one name, and the failure
+ * would be that one of them silently stops: it would look exactly like
+ * "someone else holds it", which is the ordinary case on every instance but
+ * one, so nothing would be logged.
+ */
+export function liveFeedLeaseName(domainId: string, instanceId: string, source?: string): string {
+  for (const [what, value] of [
+    ['domainId', domainId],
+    ['instanceId', instanceId]
+  ] as const) {
+    if (!value || !String(value).trim()) {
+      throw new Error(`cannot name a live feed lease without ${what} — two feeds would share one name`)
+    }
+  }
+
+  const named = source && String(source).trim()
+
+  return named ? `${PREFIX}::${domainId}::${instanceId}::${named}` : `${PREFIX}::${domainId}::${instanceId}`
+}

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

@@ -0,0 +1,94 @@
+/*
+ * **원본이 준 레코드를 트윈에 넣는다** — 밀어 받는 길과 backfill 이 같이 쓴다.
+ *
+ * ── 왜 한 곳에 두나 ─────────────────────────────────────────────────────────
+ * 이 몸통이 `routes.ts` 의 훅 안에 박혀 있었습니다. backfill 문을 만들면서 복사하면 두 길이 서로
+ * 다른 규칙으로 받게 되고, 한쪽만 수정되는 날이 옵니다.
+ *
+ * 실제로 그 위험이 이 자리에 있습니다. 유입 장부의 네 갈래(앉음 · 되풀이 · 어휘 · 거절)를
+ * 2026-09-05 에 고쳤는데, 그때 이 몸통이 두 벌이었다면 한쪽 셈만 닫혔을 것입니다.
+ *
+ * ── 커널을 직접 부르지 않는 쪽이 넘겨받는다 ────────────────────────────────
+ * 훅 판정(`reference-hook.ts`)은 이 함수를 인자로 받습니다. 그 파일이 엔진을 직접 부르면 테스트할
+ * 때 엔진이 필요해집니다. 그 규율은 그대로 두고, 이 파일이 엔진을 아는 유일한 자리가 됩니다.
+ */
+import type { IngestResult } from './reference-hook.js'
+
+import { TwinEngine } from '../../engine/index.js'
+import { ingestCanonicalRecords } from '../../engine/canonical-ingest.js'
+import { databaseCommandStore, settleEffects } from '../actuation/index.js'
+import { shouldHaveTime } from '../../engine/event-time.js'
+import { twinWarn } from '../../engine/log.js'
+
+/**
+ * 레코드를 넣고 **네 갈래로 답한다.**
+ *
+ * 두 갈래로는 셈이 안 닫힙니다(인티그레이션 레인 실측 2026-09-05).
+ *
+ * ```
+ * 두 갈래   157 − 46 − 2 = 109 「설명 못 함」   진실은 되풀이 108 + 어휘 1
+ * 네 갈래   157 − 46 − 2 − 108 − 1 = 0
+ * ```
+ *
+ * 109 를 「사라졌다」로 내면 그날부터 아무도 그 수를 안 봅니다. 늘 참인 경고는 벽지가 됩니다.
+ *
+ * `vocabulary` 는 저널에 안 가는 어휘 요소의 수입니다. 사라진 것이 아닙니다.
+ *
+ * @param via 유입 장부에 남길 길 이름 — `hook`(밀어 받음) · `fill`(빠진 구간을 다시 받음)
+ */
+export function liveIngest(
+  domainId: string,
+  instanceId: string,
+  records: unknown[],
+  via: string
+): IngestResult & { vocabulary: number; undated?: Record<string, number> } {
+  const { accepted, rejected, masterData, undated } = ingestCanonicalRecords(
+    records as any,
+    domainId,
+    new Date().toISOString(),
+    TwinEngine.factScope(domainId, instanceId)
+  )
+  /* 사건이 아닌 것은 상태만 세운다 — 두 길이 같은 규율이다(§`applyMasterData`). */
+  if (masterData.length) TwinEngine.applyMasterData(domainId, instanceId, masterData)
+  const { applied, duplicates } = TwinEngine.ingestLiveResult(domainId, instanceId, accepted, via)
+
+  /*
+   * **나간 지시와 잇는다** — 폐루프. 기다리지 않습니다: 훅의 응답이 이것 때문에 늦으면 보내는 쪽이
+   * 되풀이하고, 그러면 같은 관측이 두 번 옵니다. 실패해도 관측 유입은 멈추지 않습니다.
+   */
+  void settleEffects({ domainId, envelopes: accepted, store: databaseCommandStore() })
+
+  /*
+   * 커널이 받지 못한 수를 이름으로 남깁니다 — 트윈이 멈춘 사이 버려진 레코드를 「통과」로 세면
+   * 화면이 100% 라고 말합니다. 중복으로 걸러진 것은 버려진 것이 아니므로 빼고 셉니다.
+   */
+  const undelivered = Math.max(0, accepted.length - applied - duplicates)
+  TwinEngine.recordIngestResult(domainId, instanceId, records.length, rejected, Date.now(), undelivered, masterData.length)
+
+  /*
+   * 떨어진 것을 **수가 아니라 목록으로** 넘깁니다 — 응답에 실어야 보내는 쪽이 그것만 따로 둘 수
+   * 있습니다. 수만 주면 배치 전체를 다시 보내거나 전부 버리는 두 갈래밖에 없습니다.
+   */
+  /*
+   * **표에 있는 type 인데 시각을 못 읽었으면 그것은 결함이다.** 그 fact 는 자기 시각을 싣기로 되어
+   * 있는데 안 실려 온 것이고, 그대로 두면 ingest 시각이 그 사실의 시각으로 저장된다.
+   *
+   * 표에 없는 type 은 세기만 한다 — 절대값 snapshot 은 polling 순간이 맞는 시각이다.
+   */
+  const wrong = Object.entries(undated ?? {}).filter(([type]) => shouldHaveTime(type))
+  if (wrong.length) {
+    twinWarn(
+      `[twin-ingest] "${instanceId}" — 시각을 실어야 하는 fact 가 시각 없이 왔습니다: ` +
+        wrong.map(([t, n]) => `${t} ${n}건`).join(' · ') +
+        `. 그 사실들은 지금 시각으로 저널에 앉습니다`
+    )
+  }
+
+  return {
+    applied,
+    duplicates,
+    vocabulary: masterData.length,
+    rejected,
+    ...(undated && Object.keys(undated).length ? { undated } : {})
+  }
+}