@things-factory/headless-twin 10.1.7 → 10.1.10

package/dist-server/service/reference/reference-hook.js.map

@@ -1 +1 @@
-{"version":3,"file":"reference-hook.js","sourceRoot":"","sources":["../../../server/service/reference/reference-hook.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 연결된 시스템이 **밀어 주는** 사실을 받는 자리 — 웹훅.\n *\n * 규약(상태 코드 · 비밀값 · 대상 확인)은 `hook-contract.ts` 에 있다. 여기는 그것을 써서 찾고 · 확인하고 ·\n * 커넥터에게 옮기게 하고 · 유입으로 넘기는 순서만 맡는다.\n *\n * ── 왜 필요한가 ─────────────────────────────────────────────────────────────\n * 지금 모든 커넥터가 주기적으로 물어봅니다(폴링). 그 방식은 두 가지를 치릅니다. 연결된 시스템이 값을\n * 갱신하는 주기보다 자주 물으면 같은 값을 되풀이 받고, 그쪽 서버에 그만큼 부담을 줍니다. 실제로\n * 태양광 발전소에 10초마다 물으면서 10분마다 바뀌는 값을 받아 왔습니다.\n *\n * 연결된 시스템이 「바뀌었다」를 말해 줄 수 있으면 그것을 받는 것이 낫습니다. 이 파일이 그 입구입니다.\n *\n * ── 규약 ────────────────────────────────────────────────────────────────────\n *\n *   주소     POST /domain/<도메인>/twin/hook/<연결이름>/<트윈>\n *   인증     연결 설정에 저장한 비밀값(`hookSecret`)을 헤더로 보낸다\n *            X-Twin-Hook-Secret: <비밀값>   또는   Authorization: Bearer <비밀값>\n *   본문     연결된 시스템이 정한 모양 그대로. 우리 어휘로 옮기는 것은 커넥터의 일이다\n *   응답     아래 §`hookStatus`\n *\n * ── 왜 사람 인증(JWT)이 아닌가 ──────────────────────────────────────────────\n * 밀어 주는 쪽은 사람이 아닙니다. 우리 토큰을 발급받아 갱신하며 관리하라고 요구하면 대부분의 현장에서\n * 연동이 서지 않습니다. 그래서 연결마다 비밀값을 두고 그것으로 확인합니다.\n *\n * **비밀값이 없는 연결은 훅을 받지 않습니다.** 기본이 거부입니다 — 인증 없는 입구를 열어 두는 것보다\n * 훅을 못 쓰는 것이 낫습니다.\n *\n * ── 왜 커넥터가 옮기나 (시나리오가 아니라) ──────────────────────────────────\n * 연결된 시스템의 웹훅은 그쪽이 정한 고정된 모양으로 옵니다. 그 모양을 아는 것은 그 커넥터이고,\n * 옮기는 판단은 코드여야 테스트로 지킬 수 있습니다. 실제로 지금 커넥터들이 코드로 판단합니다 —\n * 통신이 끊긴 설비의 값은 보내지 않고, 잰 시각이 나아가지 않은 줄은 거릅니다. 그 판단을 변환식으로\n * 옮기면 약해지고 테스트가 없어집니다.\n *\n * ── 밀어 주기만으로는 안 된다 ───────────────────────────────────────────────\n * 훅은 반드시 놓칩니다 — 우리가 내려가 있을 때, 그쪽이 못 보냈을 때, 네트워크가 끊겼을 때. 그래서\n * 훅을 쓰는 연결도 **드문 폴링을 유지합니다.** 폴링의 역할이 「값을 가져오는 것」에서 「놓친 것이 있나\n * 확인하는 것」으로 바뀌는 것입니다. 그 주기는 연결 설정이 정합니다.\n *\n * ── 같은 것이 두 번 오는 것 ─────────────────────────────────────────────────\n * 밀어 주는 방식은 재전송이 정상입니다(그쪽이 우리 응답을 못 받으면 다시 보냅니다). 그것은 유입\n * 경계가 이미 거릅니다(§`FactDeduper`) — 이 파일이 따로 하지 않습니다. 응답에 몇 건이 중복이었는지\n * 함께 알립니다.\n */\nimport { WEBHOOK_STATUS, type WebhookResponse } from '@operato/ops-contract'\n\nimport { twinWarn } from '../../engine/log.js'\n\nimport { getAdapter, type InboundBatch } from './reference-adapter.js'\nimport { rejectedForCaller, type RejectedForCaller } from './hook-rejected.js'\nexport { rejectedForCaller, type RejectedForCaller } from './hook-rejected.js'\nimport { authorizeHook, producedInstance, pushCursorKey, seqOf, takeInSequence, withSeq, type HookOutcome } from './hook-contract.js'\n\n/**\n * 훅 하나를 처리한다 — 찾고 · 확인하고 · 커넥터에게 옮기게 하고 · 유입으로 넘긴다.\n *\n * 유입 자체(`ingest`)는 부르는 쪽이 넘겨 준다: 이 파일이 엔진을 직접 부르면 시험할 때 엔진이 필요해지고,\n * 그러면 규약을 확인하는 시험을 쓸 수 없다.\n */\nexport async function handleHook(args: {\n  domainId: string\n  source: string\n  instanceId: string\n  headers: Record<string, unknown>\n  body: unknown\n  /**\n   * 받은 바이트 그대로 — 서명을 확인하려면 이것이 있어야 한다.\n   *\n   * 파싱한 객체를 다시 문자열로 만들면 키 순서와 공백이 달라져 서명이 맞지 않는다. 없으면 서명을 쓰는\n   * 요청은 거절된다(§`authorizeHook`).\n   */\n  rawBody?: string\n  /** 서명 창을 재는 기준 시각. 부르는 쪽이 준다 — 여기서 읽으면 시험이 시계에 매인다. */\n  nowMs?: number\n  /** 레코드를 트윈에 넣는다 — 받은 수와 **떨어진 것들**을 돌려준다. */\n  ingest: (instanceId: string, records: unknown[]) => IngestResult\n  /**\n   * 구멍을 봤다 — **부르는 쪽이 무엇을 할지 정한다.**\n   *\n   * 여기서 backfill 을 직접 부르지 않는다. 이 파일은 `ingest`·`store` 를 인자로 받아 가볍게 유지한다\n   * (그래야 테스트가 엔진 없이 이 판정을 확인할 수 있다). backfill 을 import 하면 그 규율이 깨진다.\n   *\n   * 기다리지 않는 것도 부르는 쪽의 몫이다 — 훅의 응답이 늦으면 보내는 쪽이 되풀이한다.\n   */\n  onGap?: (scope: string) => void\n  /**\n   * 저장소를 대신 쓰는 자리 — **시험이 재기동을 넣을 수 있게.**\n   *\n   * `ingest` 를 부르는 쪽이 넘겨 주는 것과 같은 이유다(위 §). 커서는 재기동을 넘어 살아야 하는데, 한\n   * 프로세스 안에서만 확인하면 「적히나」는 보이지만 「다시 세우면 읽히나」는 안 보인다. 그 둘이 갈린\n   * 결함을 이 저장소가 이미 겪었다.\n   */\n  store: HookStore\n}): Promise<HookOutcome> {\n  const { domainId, source, instanceId, headers, body, rawBody, ingest, onGap } = args\n  const nowMs = args.nowMs ?? Date.now()\n  const { store } = args\n\n  const ref = await store.load(domainId, source)\n  if (!ref) {\n    return { status: WEBHOOK_STATUS.unknownTarget, body: { ok: false, error: `unknown connection \"${source}\"` } }\n  }\n\n  const cfg: any = (ref as any).connectionConfig ?? {}\n  const expected = String(cfg.hookSecret ?? '').trim()\n  if (!expected) {\n    /* 비밀값을 선언하지 않은 연결은 훅을 받지 않는다 — 기본이 거부다. */\n    return {\n      status: WEBHOOK_STATUS.badSecret,\n      body: {\n        ok: false,\n        error: `connection \"${source}\" declares no hookSecret — set one in the connection settings before pushing to it`\n      }\n    }\n  }\n  const auth = authorizeHook({ headers, rawBody, secret: expected, nowMs })\n  if (auth.ok === false) {\n    return { status: WEBHOOK_STATUS.badSecret, body: { ok: false, error: auth.reason } }\n  }\n\n  const site = producedInstance(ref as any, instanceId)\n  if (!site) {\n    return {\n      status: WEBHOOK_STATUS.unknownTarget,\n      body: { ok: false, error: `twin \"${instanceId}\" was not created by connection \"${source}\"` }\n    }\n  }\n\n  const adapter: any = getAdapter(String((ref as any).adapterType ?? ''))\n  if (typeof adapter?.handleInbound !== 'function') {\n    return {\n      status: WEBHOOK_STATUS.unsupported,\n      body: { ok: false, error: `connector \"${(ref as any).adapterType}\" cannot take pushed events (no handleInbound)` }\n    }\n  }\n\n  let batch: InboundBatch\n  try {\n    batch = adapter.handleInbound(cfg, site, body, headers)\n  } catch (e: any) {\n    /* 옮기지 못한 것은 그쪽 모양이 바뀐 것이다 — 다시 보내도 같으므로 재시도를 부르지 않는다. */\n    return { status: WEBHOOK_STATUS.badPayload, body: { ok: false, error: e?.message ?? 'cannot translate the payload' } }\n  }\n  const items = batch?.items\n  if (!Array.isArray(items)) {\n    return {\n      status: WEBHOOK_STATUS.badPayload,\n      body: { ok: false, error: 'the connector did not return a list of items' }\n    }\n  }\n\n  /*\n   * **번호 확인** — 이 자리가 프레임워크인 이유는 밀어 주는 모든 연결에 같은 규율이라야 하기 때문이다.\n   * 커넥터마다 만들면 한 곳이 빠지고, 빠진 그 연결에서만 사실이 없어진다.\n   *\n   * 판정은 `takeInSequence` 하나가 한다 — **backfill 하는 길도 같은 함수를 지난다.** 여기서 따로 만들면\n   * 두 길이 다른 규칙으로 받고, 한쪽만 고쳐지는 날이 온다.\n   */\n  const scope = typeof batch.scope === 'string' && batch.scope.trim() ? batch.scope.trim() : undefined\n  /* 열쇠에 트윈을 넣는다 — 연결 하나가 트윈 여럿을 만들고 커서는 연결마다 한 행이다. */\n  const key = scope ? pushCursorKey(instanceId, scope) : undefined\n  const taken = takeInSequence({\n    items,\n    scope,\n    lastSeq: key ? seqOf((ref as any).liveCursor, key) : undefined\n  })\n  if (taken.refused) {\n    /* 반쯤 확인한 것을 확인했다고 말하지 않는다. */\n    return { status: WEBHOOK_STATUS.badPayload, body: { ok: false, error: taken.refused } }\n  }\n  const numbered = taken.numbered\n  const gap = taken.gap\n  /*\n   * 첫 봉투가 1번이 아니면 **그 사실을 남긴다.** 커서가 없는 연결에 21번이 오면 커서가 21 로 뛰고,\n   * 그 앞 스무 건은 구멍으로도 안 세어진다. 실제로 plant 에서 그렇게 스무 건이 조용히 사라졌다.\n   *\n   * 손실이라고 말하지 않는다 — 늦게 붙은 트윈은 그 앞을 안 받기로 한 것이다. 수만 말하고 판단은\n   * 사람이 한다.\n   */\n  if (taken.firstUnseenBefore) {\n    twinWarn(\n      `[twin-ingest] \"${instanceId}\" 의 ${scope ?? '(단위 없음)'} 를 ${taken.advancedSeq} 번부터 받기 시작했습니다 — ` +\n        `그 앞 ${taken.firstUnseenBefore}건은 받은 적이 없습니다. 원본이 오래 돌고 있었으면 정상이고, ` +\n        `보냈는데 못 받은 것이면 그만큼이 빠진 것입니다`\n    )\n  }\n  const advanced = taken.advancedSeq !== undefined && key ? { scope: key, seq: taken.advancedSeq } : undefined\n\n  const records = taken.records\n\n  if (!records.length) {\n    /*\n     * 옮길 것이 없는 것은 오류가 아니다 — 그쪽이 우리와 무관한 것을 보낸 것일 수 있다. 다만 첫 봉투부터\n     * 구멍이면 그것은 받은 것이 없는 것이고, 그 앞부터 달라고 해야 한다.\n     */\n    if (gap) {\n      if (scope) onGap?.(scope)\n      return gapOutcome(scope, gap)\n    }\n    if (advanced) await saveSeq(store, ref as any, advanced.scope, advanced.seq, taken.firstSeq)\n    return {\n      status: WEBHOOK_STATUS.ok,\n      body: {\n        ok: true,\n        offered: 0,\n        applied: 0,\n        duplicates: 0,\n        vocabulary: 0,\n        rejected: [],\n        ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)\n      }\n    }\n  }\n\n  let result: IngestResult\n  try {\n    result = ingest(instanceId, records)\n  } catch (e: any) {\n    return { status: WEBHOOK_STATUS.failed, body: { ok: false, error: e?.message ?? 'ingest failed' } }\n  }\n  const rejected = result.rejected ?? []\n  /*\n   * ── 떨어진 것에 **봉투 id** 를 붙인다 (2026-09-07 측정) ──────────────────────\n   * 이 응답이 `{ record, errors }` 목록이었고, plant 은 그것을 **봉투 id 문자열 목록**으로 읽고\n   * 있었다. `Array.isArray` 는 통과하므로 그쪽 guard 도 안 걸렸다 — id 를 맞추는데 객체라 하나도\n   * 안 맞고 **묶음 전체가 「보냈음」으로 찍혔다.**\n   *\n   * 422 와 `ok: false` 를 보냈는데 그쪽 행은 재시도 0 · 오류 없음 · 보냈음이었다. 우리가 말했는데\n   * 상대가 못 알아듣는 모양이면, 말한 것이 아니다.\n   *\n   * 그래서 봉투 id 를 함께 싣는다. 보내는 쪽이 자기 행을 표시할 수 있고 까닭도 남는다.\n   *\n   * **id 를 못 찾으면 레코드를 그대로 싣는다.** 그때는 무엇이 떨어졌는지 알 방법이 그것뿐이고,\n   * 빈 id 를 실으면 보내는 쪽이 아무 행도 못 찾으면서 「알았다」고 여긴다.\n   *\n   * 짝은 **객체 동일성**으로 짓는다. `records` 는 `items` 의 순서와 원소를 그대로 들고 있고\n   * (§`takeInSequence`), 그래서 커넥터를 고치지 않고도 봉투로 되짚을 수 있다. 값으로 비교하면\n   * 같은 모양의 레코드 둘이 서로의 id 를 가져간다.\n   */\n  const forCaller = rejectedForCaller(rejected, items as { record?: unknown; eventId?: unknown }[])\n\n  if (result.applied === 0 && result.duplicates === 0 && rejected.length === 0 && !result.vocabulary) {\n    /*\n     * 넣었는데 한 건도 반영되지 않았고 중복도 거부도 아니면, 그 트윈이 실시간으로 돌지 않는 것이다.\n     * 200 을 주면 그쪽은 전달된 줄 알고 그 사실을 버린다.\n     *\n     * **커서를 올리지 않는다.** 한 건도 안 들어갔는데 번호를 올리면 그 번호는 다시 오지 않고, 트윈이\n     * 뜬 뒤에 그 구간이 비어 있게 된다.\n     *\n     * ── Vocabulary is why this test needs a fourth term (2026-09-07) ──────────\n     * This inference reads an absence as a cause, and one absence is legitimate: a batch that was\n     * entirely vocabulary applies no events, has no duplicates and rejects nothing, and yet\n     * everything in it landed (§`applyMasterData`). Without the last term the receiver answers\n     * 503 to correct traffic, and the sender then holds those facts and retries every thirty\n     * seconds for as long as they keep arriving — the reply invents a reason (\"not running live\")\n     * that the numbers do not support.\n     *\n     * Found by a test written for the response sum, not by reading this line.\n     *\n     * ── Why this branch has to say something out loud ─────────────────────────\n     * Measured today: a 503 from here leaves **no trace on either side.** The sender maps it to\n     * backpressure and returns without touching `attempts` or `lastError`, and this branch logged\n     * nothing, so a sender re-offering the same batch every thirty seconds is invisible to both.\n     *\n     * That is also why \"it has not happened\" could not be established: `attempts 0` on the seven\n     * vocabulary envelopes was offered as evidence and is not evidence, because this path never\n     * increments that counter. Telling a sender to come back forever is worth one line.\n     */\n    twinWarn(\n      `[twin-hook] \"${instanceId}\" 에 ${records.length}건이 왔는데 한 건도 앉지 않아 ` +\n        `${NOT_LIVE_RETRY_MS / 1000}초 뒤 다시 오라고 답했습니다 — 트윈이 실시간으로 돌지 않는 것으로 봅니다. ` +\n        `보내는 쪽은 이 답에 재시도 횟수를 남기지 않으므로, 되풀이되면 이 줄만 늘어납니다`\n    )\n\n    return {\n      status: WEBHOOK_STATUS.notLive,\n      body: {\n        ok: false,\n        error: `twin \"${instanceId}\" is not running live — nothing was applied`,\n        offered: records.length,\n        retryAfterMs: NOT_LIVE_RETRY_MS\n      }\n    }\n  }\n\n  if (advanced) await saveSeq(store, ref as any, advanced.scope, advanced.seq, taken.firstSeq)\n\n  /*\n   * **구멍이 있으면 그것이 답을 정한다.** 앞의 것은 이미 들어갔으므로 `lastSeq` 까지는 보냄으로 표시하게\n   * 하고, 떨어진 것이 있으면 그것도 함께 싣는다 — 두 소식이 한 응답에 들어가야 보내는 쪽이 둘 다 한다.\n   */\n  if (gap) {\n    if (scope) onGap?.(scope)\n    return gapOutcome(scope, gap, forCaller, advanced)\n  }\n\n  if (rejected.length) {\n    /*\n     * **다시 보내라고 하지 않는다.** 떨어진 것은 모양이 틀린 것이라 같은 것을 다시 보내도 또 떨어지고,\n     * 함께 간 나머지는 이미 들어갔으므로 두 번 들어간다.\n     */\n    return {\n      status: WEBHOOK_STATUS.partial,\n      body: {\n        ok: false,\n        error: `${rejected.length} of ${records.length} records did not pass validation`,\n        offered: records.length,\n        applied: result.applied,\n        duplicates: result.duplicates,\n        vocabulary: result.vocabulary ?? 0,\n        rejected: forCaller,\n        ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)\n      }\n    }\n  }\n\n  return {\n    status: WEBHOOK_STATUS.ok,\n    body: {\n      ok: true,\n      offered: records.length,\n      applied: result.applied,\n      duplicates: result.duplicates,\n      /*\n       * Always reported, even as zero — the sender's sum has a term for it either way, and a field\n       * that appears only sometimes makes an absent one indistinguishable from a receiver that\n       * does not count vocabulary at all.\n       */\n      vocabulary: result.vocabulary ?? 0,\n      rejected: [],\n      ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)\n    }\n  }\n}\n\n/**\n * 유입이 돌려주는 것.\n *\n * 떨어진 것을 **수가 아니라 목록으로** 받는다. 수만 받으면 보내는 쪽에 「몇 건이 떨어졌다」밖에 말할 수\n * 없고, 그러면 무엇을 따로 두어야 할지 알 수 없어 배치 전체를 다시 보내거나 전부 버린다.\n */\nexport interface IngestResult {\n  applied: number\n  duplicates: number\n  rejected: { record: unknown; errors: string[] }[]\n  /**\n   * How many records were vocabulary rather than events — **needed so the reply's sum closes.**\n   *\n   * `liveIngest` has counted this all along and this boundary dropped it, because the callback was\n   * typed as `IngestResult` and vocabulary was not on it. So `offered` counted those records and\n   * none of the other three did, and a sender checking the sum would have seen a loss on ordinary\n   * traffic (§`WebhookResponse.offered`).\n   *\n   * Optional because an ingest that handles no vocabulary need not say zero, and a caller that\n   * simply does not know must not be made to claim none.\n   */\n  vocabulary?: number\n}\n\n/**\n * 구멍을 알리는 응답 — **앞의 것은 받았다는 것을 함께 말한다.**\n *\n * `lastSeq` 를 빼면 보내는 쪽은 이미 들어간 것까지 다시 보내고, 그것이 매번 중복으로 걸러지면서\n * 처리량만 먹는다.\n */\n/*\n * 구멍을 본 자리에서 **바로 받는다** — 번호가 비었다는 것을 아는 가장 이른 순간이다.\n *\n * 기다리지 않는다. 훅의 응답이 이것 때문에 늦으면 보내는 쪽이 되풀이하고, 그러면 같은 봉투가 두 번\n * 온다. 그리고 같은 단위를 1분 안에 두 번 부르지 않는다(§`FILL_DEBOUNCE_MS`) — 밀어 받는 쪽이\n * 구멍 뒤의 봉투를 계속 보내면 그때마다 구멍 판정이 나기 때문이다.\n */\nfunction gapOutcome(\n  scope: string | undefined,\n  gap: { expectedSeq: number; lastSeq: number },\n  /*\n   * 떨어진 것 — 봉투 id 를 알면 그것을, 모르면 레코드를 싣는다(§`InboundItem.eventId`).\n   * 보내는 쪽이 자기 행을 찾을 수 있어야 하고, 못 찾으면 무엇이 떨어졌는지라도 보여야 한다.\n   */\n  rejected: RejectedForCaller[] = [],\n  advanced?: { scope: string; seq: number }\n): HookOutcome {\n  return {\n    status: WEBHOOK_STATUS.sequenceGap,\n    body: {\n      ok: false,\n      error: 'sequence gap',\n      scope,\n      expectedSeq: gap.expectedSeq,\n      lastSeq: advanced?.seq ?? gap.lastSeq,\n      ...(rejected.length ? { rejected } : {})\n    }\n  }\n}\n\n/**\n * 트윈이 안 돌 때 얼마나 쉬라고 할 것인가.\n *\n * 사람이 트윈을 띄워야 풀리므로 초 단위로 다시 두드릴 이유가 없다. 그렇다고 길게 잡으면 트윈이 뜬 뒤\n * 그만큼 늦게 이어진다.\n */\nconst NOT_LIVE_RETRY_MS = 30_000\n\n/**\n * 응답에 번호를 어떻게 적나 — **확인한 것과 확인하지 않은 것을 구별한다.**\n *\n * 번호를 매기지 않는 원본은 확인할 것이 없다. 그것을 응답에서 「이상 없다」와 같아 보이게 두면, 어느\n * 연결이 연속성을 지키고 있는지 아무도 알 수 없다.\n */\n/*\n * The return type is the contract's, narrowed to the fields this function fills.\n *\n * It was `Record<string, unknown>`, and because the result is **spread** into the reply, an index\n * signature slips past the excess-property check entirely — the four fields below were unverified\n * even after `HookOutcome.body` was typed. Naming them here is what makes the check reach them.\n */\nfunction seqBody(\n  scope: string | undefined,\n  advanced: { scope: string; seq: number } | undefined,\n  numbered: boolean,\n  firstUnseenBefore?: number\n): Pick<WebhookResponse, 'sequenceChecked' | 'scope' | 'lastSeq' | 'firstUnseenBefore'> {\n  if (!numbered) return { sequenceChecked: false }\n  return {\n    sequenceChecked: true,\n    scope,\n    lastSeq: advanced?.seq,\n    /*\n     * 첫 봉투였고 그 앞을 못 봤으면 **그 수를 보내는 쪽에 돌려준다.** 안 돌려주면 그 사실이 아무 데도\n     * 안 남는다 — 구멍으로도 안 세어지고 backfill 대상도 아니다(backfill 은 커서부터 묻는다).\n     */\n    ...(firstUnseenBefore ? { firstUnseenBefore } : {})\n  }\n}\n\n/**\n * 커서에 번호를 적는다 — **반영한 뒤에만.**\n *\n * 넣기 전에 올리면, 넣다가 실패했을 때 그 번호는 다시 오지 않는다. 보내는 쪽은 200 을 못 받았으니 다시\n * 보내겠지만, 그때는 커서가 이미 지나가 있어 `behind` 로 읽히고 버려진다.\n *\n * 적지 못하는 것은 사실 유입을 무르는 이유가 아니다 — 이미 들어간 사실은 그대로 두고, 다음 번호가 오면\n * `gap` 으로 드러난다. 그래서 실패를 던지지 않고 남긴다.\n */\nasync function saveSeq(\n  store: HookStore,\n  ref: { id: string; liveCursor?: unknown },\n  scope: string,\n  seq: number,\n  firstSeq?: number\n): Promise<void> {\n  const next = withSeq(ref.liveCursor, scope, seq, firstSeq)\n  ref.liveCursor = next\n  await store\n    .saveCursor(ref.id, next)\n    .catch(err => twinWarn(`[twin-hook] 번호를 커서에 적지 못했다 (${scope}=${seq}) — ${err?.message ?? err}`))\n}\n\n/**\n * 훅이 저장소에 닿는 두 자리 — 연결을 찾는 것과 커서를 적는 것.\n *\n * 이 둘만 밖으로 낸다. 나머지는 인자만 보고 답하므로 시험이 데이터베이스를 세우지 않아도 된다.\n */\nexport interface HookStore {\n  load(domainId: string, source: string): Promise<any | null>\n  saveCursor(refId: string, cursor: unknown): Promise<void>\n}\n\n"]}
+{"version":3,"file":"reference-hook.js","sourceRoot":"","sources":["../../../server/service/reference/reference-hook.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 연결된 시스템이 **밀어 주는** 사실을 받는 자리 — 웹훅.\n *\n * 규약(상태 코드 · 비밀값 · 대상 확인)은 `hook-contract.ts` 에 있다. 여기는 그것을 써서 찾고 · 확인하고 ·\n * 커넥터에게 옮기게 하고 · 유입으로 넘기는 순서만 맡는다.\n *\n * ── 왜 필요한가 ─────────────────────────────────────────────────────────────\n * 지금 모든 커넥터가 주기적으로 물어봅니다(폴링). 그 방식은 두 가지를 치릅니다. 연결된 시스템이 값을\n * 갱신하는 주기보다 자주 물으면 같은 값을 되풀이 받고, 그쪽 서버에 그만큼 부담을 줍니다. 실제로\n * 태양광 발전소에 10초마다 물으면서 10분마다 바뀌는 값을 받아 왔습니다.\n *\n * 연결된 시스템이 「바뀌었다」를 말해 줄 수 있으면 그것을 받는 것이 낫습니다. 이 파일이 그 입구입니다.\n *\n * ── 규약 ────────────────────────────────────────────────────────────────────\n *\n *   주소     POST /domain/<도메인>/twin/hook/<연결이름>/<트윈>\n *   인증     연결 설정에 저장한 비밀값(`hookSecret`)을 헤더로 보낸다\n *            X-Twin-Hook-Secret: <비밀값>   또는   Authorization: Bearer <비밀값>\n *   본문     연결된 시스템이 정한 모양 그대로. 우리 어휘로 옮기는 것은 커넥터의 일이다\n *   응답     아래 §`hookStatus`\n *\n * ── 왜 사람 인증(JWT)이 아닌가 ──────────────────────────────────────────────\n * 밀어 주는 쪽은 사람이 아닙니다. 우리 토큰을 발급받아 갱신하며 관리하라고 요구하면 대부분의 현장에서\n * 연동이 서지 않습니다. 그래서 연결마다 비밀값을 두고 그것으로 확인합니다.\n *\n * **비밀값이 없는 연결은 훅을 받지 않습니다.** 기본이 거부입니다 — 인증 없는 입구를 열어 두는 것보다\n * 훅을 못 쓰는 것이 낫습니다.\n *\n * ── 왜 커넥터가 옮기나 (시나리오가 아니라) ──────────────────────────────────\n * 연결된 시스템의 웹훅은 그쪽이 정한 고정된 모양으로 옵니다. 그 모양을 아는 것은 그 커넥터이고,\n * 옮기는 판단은 코드여야 테스트로 지킬 수 있습니다. 실제로 지금 커넥터들이 코드로 판단합니다 —\n * 통신이 끊긴 설비의 값은 보내지 않고, 잰 시각이 나아가지 않은 줄은 거릅니다. 그 판단을 변환식으로\n * 옮기면 약해지고 테스트가 없어집니다.\n *\n * ── 밀어 주기만으로는 안 된다 ───────────────────────────────────────────────\n * 훅은 반드시 놓칩니다 — 우리가 내려가 있을 때, 그쪽이 못 보냈을 때, 네트워크가 끊겼을 때. 그래서\n * 훅을 쓰는 연결도 **드문 폴링을 유지합니다.** 폴링의 역할이 「값을 가져오는 것」에서 「놓친 것이 있나\n * 확인하는 것」으로 바뀌는 것입니다. 그 주기는 연결 설정이 정합니다.\n *\n * ── 같은 것이 두 번 오는 것 ─────────────────────────────────────────────────\n * 밀어 주는 방식은 재전송이 정상입니다(그쪽이 우리 응답을 못 받으면 다시 보냅니다). 그것은 유입\n * 경계가 이미 거릅니다(§`FactDeduper`) — 이 파일이 따로 하지 않습니다. 응답에 몇 건이 중복이었는지\n * 함께 알립니다.\n */\nimport { WEBHOOK_STATUS, type WebhookResponse } from '@operato/ops-contract'\n\nimport { twinWarn } from '../../engine/log.js'\n\nimport { getAdapter, type InboundBatch } from './reference-adapter.js'\nimport { rejectedForCaller, type RejectedForCaller } from './hook-rejected.js'\nexport { rejectedForCaller, type RejectedForCaller } from './hook-rejected.js'\nimport { authorizeHook, producedInstance, pushCursorKey, seqOf, takeInSequence, withSeq, type HookOutcome } from './hook-contract.js'\n\ntype WebhookLane = 'FACTS' | 'ATTENTIONS'\nfunction webhookLaneOf(value: unknown): WebhookLane | undefined {\n  return value === undefined || value === 'FACTS' ? 'FACTS' : value === 'ATTENTIONS' ? 'ATTENTIONS' : undefined\n}\n\n/**\n * 훅 하나를 처리한다 — 찾고 · 확인하고 · 커넥터에게 옮기게 하고 · 유입으로 넘긴다.\n *\n * 유입 자체(`ingest`)는 부르는 쪽이 넘겨 준다: 이 파일이 엔진을 직접 부르면 시험할 때 엔진이 필요해지고,\n * 그러면 규약을 확인하는 시험을 쓸 수 없다.\n */\nexport async function handleHook(args: {\n  domainId: string\n  source: string\n  instanceId: string\n  headers: Record<string, unknown>\n  body: unknown\n  /**\n   * 받은 바이트 그대로 — 서명을 확인하려면 이것이 있어야 한다.\n   *\n   * 파싱한 객체를 다시 문자열로 만들면 키 순서와 공백이 달라져 서명이 맞지 않는다. 없으면 서명을 쓰는\n   * 요청은 거절된다(§`authorizeHook`).\n   */\n  rawBody?: string\n  /** 서명 창을 재는 기준 시각. 부르는 쪽이 준다 — 여기서 읽으면 시험이 시계에 매인다. */\n  nowMs?: number\n  /** 레코드를 트윈에 넣는다 — 받은 수와 **떨어진 것들**을 돌려준다. */\n  ingest: (instanceId: string, records: unknown[], lane: WebhookLane) => IngestResult | Promise<IngestResult>\n  /**\n   * 구멍을 봤다 — **부르는 쪽이 무엇을 할지 정한다.**\n   *\n   * 여기서 backfill 을 직접 부르지 않는다. 이 파일은 `ingest`·`store` 를 인자로 받아 가볍게 유지한다\n   * (그래야 테스트가 엔진 없이 이 판정을 확인할 수 있다). backfill 을 import 하면 그 규율이 깨진다.\n   *\n   * 기다리지 않는 것도 부르는 쪽의 몫이다 — 훅의 응답이 늦으면 보내는 쪽이 되풀이한다.\n   */\n  onGap?: (scope: string) => void\n  /**\n   * 저장소를 대신 쓰는 자리 — **시험이 재기동을 넣을 수 있게.**\n   *\n   * `ingest` 를 부르는 쪽이 넘겨 주는 것과 같은 이유다(위 §). 커서는 재기동을 넘어 살아야 하는데, 한\n   * 프로세스 안에서만 확인하면 「적히나」는 보이지만 「다시 세우면 읽히나」는 안 보인다. 그 둘이 갈린\n   * 결함을 이 저장소가 이미 겪었다.\n   */\n  store: HookStore\n}): Promise<HookOutcome> {\n  const { domainId, source, instanceId, headers, body, rawBody, ingest, onGap } = args\n  const nowMs = args.nowMs ?? Date.now()\n  const { store } = args\n\n  const ref = await store.load(domainId, source)\n  if (!ref) {\n    return { status: WEBHOOK_STATUS.unknownTarget, body: { ok: false, error: `unknown connection \"${source}\"` } }\n  }\n\n  const cfg: any = (ref as any).connectionConfig ?? {}\n  const expected = String(cfg.hookSecret ?? '').trim()\n  if (!expected) {\n    /* 비밀값을 선언하지 않은 연결은 훅을 받지 않는다 — 기본이 거부다. */\n    return {\n      status: WEBHOOK_STATUS.badSecret,\n      body: {\n        ok: false,\n        error: `connection \"${source}\" declares no hookSecret — set one in the connection settings before pushing to it`\n      }\n    }\n  }\n  const auth = authorizeHook({ headers, rawBody, secret: expected, nowMs })\n  if (auth.ok === false) {\n    return { status: WEBHOOK_STATUS.badSecret, body: { ok: false, error: auth.reason } }\n  }\n\n  const site = producedInstance(ref as any, instanceId)\n  if (!site) {\n    return {\n      status: WEBHOOK_STATUS.unknownTarget,\n      body: { ok: false, error: `twin \"${instanceId}\" was not created by connection \"${source}\"` }\n    }\n  }\n\n  const adapter: any = getAdapter(String((ref as any).adapterType ?? ''))\n  if (typeof adapter?.handleInbound !== 'function') {\n    return {\n      status: WEBHOOK_STATUS.unsupported,\n      body: { ok: false, error: `connector \"${(ref as any).adapterType}\" cannot take pushed events (no handleInbound)` }\n    }\n  }\n\n  let batch: InboundBatch\n  try {\n    batch = adapter.handleInbound(cfg, site, body, headers)\n  } catch (e: any) {\n    /* 옮기지 못한 것은 그쪽 모양이 바뀐 것이다 — 다시 보내도 같으므로 재시도를 부르지 않는다. */\n    return { status: WEBHOOK_STATUS.badPayload, body: { ok: false, error: e?.message ?? 'cannot translate the payload' } }\n  }\n  const items = batch?.items\n  if (!Array.isArray(items)) {\n    return {\n      status: WEBHOOK_STATUS.badPayload,\n      body: { ok: false, error: 'the connector did not return a list of items' }\n    }\n  }\n\n  /*\n   * **번호 확인** — 이 자리가 프레임워크인 이유는 밀어 주는 모든 연결에 같은 규율이라야 하기 때문이다.\n   * 커넥터마다 만들면 한 곳이 빠지고, 빠진 그 연결에서만 사실이 없어진다.\n   *\n   * 판정은 `takeInSequence` 하나가 한다 — **backfill 하는 길도 같은 함수를 지난다.** 여기서 따로 만들면\n   * 두 길이 다른 규칙으로 받고, 한쪽만 고쳐지는 날이 온다.\n   */\n  const lane = webhookLaneOf((batch as any).lane)\n  if (!lane) {\n    return { status: WEBHOOK_STATUS.badPayload, body: { ok: false, error: 'unknown webhook lane' } }\n  }\n  const scope = typeof batch.scope === 'string' && batch.scope.trim() ? batch.scope.trim() : undefined\n  /* 열쇠에 트윈을 넣는다 — 연결 하나가 트윈 여럿을 만들고 커서는 연결마다 한 행이다. */\n  const key = scope ? pushCursorKey(instanceId, scope) : undefined\n  const taken = takeInSequence({\n    items,\n    scope,\n    lastSeq: key ? seqOf((ref as any).liveCursor, key) : undefined\n  })\n  if (taken.refused) {\n    /* 반쯤 확인한 것을 확인했다고 말하지 않는다. */\n    return { status: WEBHOOK_STATUS.badPayload, body: { ok: false, error: taken.refused } }\n  }\n  const numbered = taken.numbered\n  const gap = taken.gap\n  /*\n   * 첫 봉투가 1번이 아니면 **그 사실을 남긴다.** 커서가 없는 연결에 21번이 오면 커서가 21 로 뛰고,\n   * 그 앞 스무 건은 구멍으로도 안 세어진다. 실제로 plant 에서 그렇게 스무 건이 조용히 사라졌다.\n   *\n   * 손실이라고 말하지 않는다 — 늦게 붙은 트윈은 그 앞을 안 받기로 한 것이다. 수만 말하고 판단은\n   * 사람이 한다.\n   */\n  if (taken.firstUnseenBefore) {\n    twinWarn(\n      `[twin-ingest] \"${instanceId}\" 의 ${scope ?? '(단위 없음)'} 를 ${taken.advancedSeq} 번부터 받기 시작했습니다 — ` +\n        `그 앞 ${taken.firstUnseenBefore}건은 받은 적이 없습니다. 원본이 오래 돌고 있었으면 정상이고, ` +\n        `보냈는데 못 받은 것이면 그만큼이 빠진 것입니다`\n    )\n  }\n  const advanced = taken.advancedSeq !== undefined && key ? { scope: key, seq: taken.advancedSeq } : undefined\n\n  const records = taken.records\n\n  if (!records.length) {\n    /*\n     * 옮길 것이 없는 것은 오류가 아니다 — 그쪽이 우리와 무관한 것을 보낸 것일 수 있다. 다만 첫 봉투부터\n     * 구멍이면 그것은 받은 것이 없는 것이고, 그 앞부터 달라고 해야 한다.\n     */\n    if (gap) {\n      if (scope) onGap?.(scope)\n      return gapOutcome(scope, gap)\n    }\n    if (advanced) await saveSeq(store, ref as any, advanced.scope, advanced.seq, taken.firstSeq)\n    return {\n      status: WEBHOOK_STATUS.ok,\n      body: {\n        ok: true,\n        offered: 0,\n        applied: 0,\n        duplicates: 0,\n        vocabulary: 0,\n        rejected: [],\n        ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)\n      }\n    }\n  }\n\n  let result: IngestResult\n  try {\n    result = await ingest(instanceId, records, lane)\n  } catch (e: any) {\n    return { status: WEBHOOK_STATUS.failed, body: { ok: false, error: e?.message ?? 'ingest failed' } }\n  }\n  const rejected = result.rejected ?? []\n  /*\n   * ── 떨어진 것에 **봉투 id** 를 붙인다 (2026-09-07 측정) ──────────────────────\n   * 이 응답이 `{ record, errors }` 목록이었고, plant 은 그것을 **봉투 id 문자열 목록**으로 읽고\n   * 있었다. `Array.isArray` 는 통과하므로 그쪽 guard 도 안 걸렸다 — id 를 맞추는데 객체라 하나도\n   * 안 맞고 **묶음 전체가 「보냈음」으로 찍혔다.**\n   *\n   * 422 와 `ok: false` 를 보냈는데 그쪽 행은 재시도 0 · 오류 없음 · 보냈음이었다. 우리가 말했는데\n   * 상대가 못 알아듣는 모양이면, 말한 것이 아니다.\n   *\n   * 그래서 봉투 id 를 함께 싣는다. 보내는 쪽이 자기 행을 표시할 수 있고 까닭도 남는다.\n   *\n   * **id 를 못 찾으면 레코드를 그대로 싣는다.** 그때는 무엇이 떨어졌는지 알 방법이 그것뿐이고,\n   * 빈 id 를 실으면 보내는 쪽이 아무 행도 못 찾으면서 「알았다」고 여긴다.\n   *\n   * 짝은 **객체 동일성**으로 짓는다. `records` 는 `items` 의 순서와 원소를 그대로 들고 있고\n   * (§`takeInSequence`), 그래서 커넥터를 고치지 않고도 봉투로 되짚을 수 있다. 값으로 비교하면\n   * 같은 모양의 레코드 둘이 서로의 id 를 가져간다.\n   */\n  const forCaller = rejectedForCaller(rejected, items as { record?: unknown; eventId?: unknown }[])\n\n  if (result.applied === 0 && result.duplicates === 0 && rejected.length === 0 && !result.vocabulary) {\n    /*\n     * 넣었는데 한 건도 반영되지 않았고 중복도 거부도 아니면, 그 트윈이 실시간으로 돌지 않는 것이다.\n     * 200 을 주면 그쪽은 전달된 줄 알고 그 사실을 버린다.\n     *\n     * **커서를 올리지 않는다.** 한 건도 안 들어갔는데 번호를 올리면 그 번호는 다시 오지 않고, 트윈이\n     * 뜬 뒤에 그 구간이 비어 있게 된다.\n     *\n     * ── Vocabulary is why this test needs a fourth term (2026-09-07) ──────────\n     * This inference reads an absence as a cause, and one absence is legitimate: a batch that was\n     * entirely vocabulary applies no events, has no duplicates and rejects nothing, and yet\n     * everything in it landed (§`applyMasterData`). Without the last term the receiver answers\n     * 503 to correct traffic, and the sender then holds those facts and retries every thirty\n     * seconds for as long as they keep arriving — the reply invents a reason (\"not running live\")\n     * that the numbers do not support.\n     *\n     * Found by a test written for the response sum, not by reading this line.\n     *\n     * ── Why this branch has to say something out loud ─────────────────────────\n     * Measured today: a 503 from here leaves **no trace on either side.** The sender maps it to\n     * backpressure and returns without touching `attempts` or `lastError`, and this branch logged\n     * nothing, so a sender re-offering the same batch every thirty seconds is invisible to both.\n     *\n     * That is also why \"it has not happened\" could not be established: `attempts 0` on the seven\n     * vocabulary envelopes was offered as evidence and is not evidence, because this path never\n     * increments that counter. Telling a sender to come back forever is worth one line.\n     */\n    twinWarn(\n      `[twin-hook] \"${instanceId}\" 에 ${records.length}건이 왔는데 한 건도 앉지 않아 ` +\n        `${NOT_LIVE_RETRY_MS / 1000}초 뒤 다시 오라고 답했습니다 — 트윈이 실시간으로 돌지 않는 것으로 봅니다. ` +\n        `보내는 쪽은 이 답에 재시도 횟수를 남기지 않으므로, 되풀이되면 이 줄만 늘어납니다`\n    )\n\n    return {\n      status: WEBHOOK_STATUS.notLive,\n      body: {\n        ok: false,\n        error: `twin \"${instanceId}\" is not running live — nothing was applied`,\n        offered: records.length,\n        retryAfterMs: NOT_LIVE_RETRY_MS\n      }\n    }\n  }\n\n  if (advanced) await saveSeq(store, ref as any, advanced.scope, advanced.seq, taken.firstSeq)\n\n  /*\n   * **구멍이 있으면 그것이 답을 정한다.** 앞의 것은 이미 들어갔으므로 `lastSeq` 까지는 보냄으로 표시하게\n   * 하고, 떨어진 것이 있으면 그것도 함께 싣는다 — 두 소식이 한 응답에 들어가야 보내는 쪽이 둘 다 한다.\n   */\n  if (gap) {\n    if (scope) onGap?.(scope)\n    return gapOutcome(scope, gap, forCaller, advanced)\n  }\n\n  if (rejected.length) {\n    /*\n     * **다시 보내라고 하지 않는다.** 떨어진 것은 모양이 틀린 것이라 같은 것을 다시 보내도 또 떨어지고,\n     * 함께 간 나머지는 이미 들어갔으므로 두 번 들어간다.\n     */\n    return {\n      status: WEBHOOK_STATUS.partial,\n      body: {\n        ok: false,\n        error: `${rejected.length} of ${records.length} records did not pass validation`,\n        offered: records.length,\n        applied: result.applied,\n        duplicates: result.duplicates,\n        vocabulary: result.vocabulary ?? 0,\n        rejected: forCaller,\n        ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)\n      }\n    }\n  }\n\n  return {\n    status: WEBHOOK_STATUS.ok,\n    body: {\n      ok: true,\n      offered: records.length,\n      applied: result.applied,\n      duplicates: result.duplicates,\n      /*\n       * Always reported, even as zero — the sender's sum has a term for it either way, and a field\n       * that appears only sometimes makes an absent one indistinguishable from a receiver that\n       * does not count vocabulary at all.\n       */\n      vocabulary: result.vocabulary ?? 0,\n      rejected: [],\n      ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)\n    }\n  }\n}\n\n/**\n * 유입이 돌려주는 것.\n *\n * 떨어진 것을 **수가 아니라 목록으로** 받는다. 수만 받으면 보내는 쪽에 「몇 건이 떨어졌다」밖에 말할 수\n * 없고, 그러면 무엇을 따로 두어야 할지 알 수 없어 배치 전체를 다시 보내거나 전부 버린다.\n */\nexport interface IngestResult {\n  applied: number\n  duplicates: number\n  rejected: { record: unknown; errors: string[] }[]\n  /**\n   * How many records were vocabulary rather than events — **needed so the reply's sum closes.**\n   *\n   * `liveIngest` has counted this all along and this boundary dropped it, because the callback was\n   * typed as `IngestResult` and vocabulary was not on it. So `offered` counted those records and\n   * none of the other three did, and a sender checking the sum would have seen a loss on ordinary\n   * traffic (§`WebhookResponse.offered`).\n   *\n   * Optional because an ingest that handles no vocabulary need not say zero, and a caller that\n   * simply does not know must not be made to claim none.\n   */\n  vocabulary?: number\n}\n\n/**\n * 구멍을 알리는 응답 — **앞의 것은 받았다는 것을 함께 말한다.**\n *\n * `lastSeq` 를 빼면 보내는 쪽은 이미 들어간 것까지 다시 보내고, 그것이 매번 중복으로 걸러지면서\n * 처리량만 먹는다.\n */\n/*\n * 구멍을 본 자리에서 **바로 받는다** — 번호가 비었다는 것을 아는 가장 이른 순간이다.\n *\n * 기다리지 않는다. 훅의 응답이 이것 때문에 늦으면 보내는 쪽이 되풀이하고, 그러면 같은 봉투가 두 번\n * 온다. 그리고 같은 단위를 1분 안에 두 번 부르지 않는다(§`FILL_DEBOUNCE_MS`) — 밀어 받는 쪽이\n * 구멍 뒤의 봉투를 계속 보내면 그때마다 구멍 판정이 나기 때문이다.\n */\nfunction gapOutcome(\n  scope: string | undefined,\n  gap: { expectedSeq: number; lastSeq: number },\n  /*\n   * 떨어진 것 — 봉투 id 를 알면 그것을, 모르면 레코드를 싣는다(§`InboundItem.eventId`).\n   * 보내는 쪽이 자기 행을 찾을 수 있어야 하고, 못 찾으면 무엇이 떨어졌는지라도 보여야 한다.\n   */\n  rejected: RejectedForCaller[] = [],\n  advanced?: { scope: string; seq: number }\n): HookOutcome {\n  return {\n    status: WEBHOOK_STATUS.sequenceGap,\n    body: {\n      ok: false,\n      error: 'sequence gap',\n      scope,\n      expectedSeq: gap.expectedSeq,\n      lastSeq: advanced?.seq ?? gap.lastSeq,\n      ...(rejected.length ? { rejected } : {})\n    }\n  }\n}\n\n/**\n * 트윈이 안 돌 때 얼마나 쉬라고 할 것인가.\n *\n * 사람이 트윈을 띄워야 풀리므로 초 단위로 다시 두드릴 이유가 없다. 그렇다고 길게 잡으면 트윈이 뜬 뒤\n * 그만큼 늦게 이어진다.\n */\nconst NOT_LIVE_RETRY_MS = 30_000\n\n/**\n * 응답에 번호를 어떻게 적나 — **확인한 것과 확인하지 않은 것을 구별한다.**\n *\n * 번호를 매기지 않는 원본은 확인할 것이 없다. 그것을 응답에서 「이상 없다」와 같아 보이게 두면, 어느\n * 연결이 연속성을 지키고 있는지 아무도 알 수 없다.\n */\n/*\n * The return type is the contract's, narrowed to the fields this function fills.\n *\n * It was `Record<string, unknown>`, and because the result is **spread** into the reply, an index\n * signature slips past the excess-property check entirely — the four fields below were unverified\n * even after `HookOutcome.body` was typed. Naming them here is what makes the check reach them.\n */\nfunction seqBody(\n  scope: string | undefined,\n  advanced: { scope: string; seq: number } | undefined,\n  numbered: boolean,\n  firstUnseenBefore?: number\n): Pick<WebhookResponse, 'sequenceChecked' | 'scope' | 'lastSeq' | 'firstUnseenBefore'> {\n  if (!numbered) return { sequenceChecked: false }\n  return {\n    sequenceChecked: true,\n    scope,\n    lastSeq: advanced?.seq,\n    /*\n     * 첫 봉투였고 그 앞을 못 봤으면 **그 수를 보내는 쪽에 돌려준다.** 안 돌려주면 그 사실이 아무 데도\n     * 안 남는다 — 구멍으로도 안 세어지고 backfill 대상도 아니다(backfill 은 커서부터 묻는다).\n     */\n    ...(firstUnseenBefore ? { firstUnseenBefore } : {})\n  }\n}\n\n/**\n * 커서에 번호를 적는다 — **반영한 뒤에만.**\n *\n * 넣기 전에 올리면, 넣다가 실패했을 때 그 번호는 다시 오지 않는다. 보내는 쪽은 200 을 못 받았으니 다시\n * 보내겠지만, 그때는 커서가 이미 지나가 있어 `behind` 로 읽히고 버려진다.\n *\n * 적지 못하는 것은 사실 유입을 무르는 이유가 아니다 — 이미 들어간 사실은 그대로 두고, 다음 번호가 오면\n * `gap` 으로 드러난다. 그래서 실패를 던지지 않고 남긴다.\n */\nasync function saveSeq(\n  store: HookStore,\n  ref: { id: string; liveCursor?: unknown },\n  scope: string,\n  seq: number,\n  firstSeq?: number\n): Promise<void> {\n  const next = withSeq(ref.liveCursor, scope, seq, firstSeq)\n  ref.liveCursor = next\n  await store\n    .saveCursor(ref.id, next)\n    .catch(err => twinWarn(`[twin-hook] 번호를 커서에 적지 못했다 (${scope}=${seq}) — ${err?.message ?? err}`))\n}\n\n/**\n * 훅이 저장소에 닿는 두 자리 — 연결을 찾는 것과 커서를 적는 것.\n *\n * 이 둘만 밖으로 낸다. 나머지는 인자만 보고 답하므로 시험이 데이터베이스를 세우지 않아도 된다.\n */\nexport interface HookStore {\n  load(domainId: string, source: string): Promise<any | null>\n  saveCursor(refId: string, cursor: unknown): Promise<void>\n}\n"]}

package/dist-server/service/reference/reference-reconciliation-query.d.ts

@@ -0,0 +1,5 @@
+import { TwinReferenceReconciliation } from './twin-reference-reconciliation.js';
+export declare class TwinReferenceReconciliationQuery {
+    twinReferenceReconciliations(instanceId: string, context: ResolverContext): Promise<TwinReferenceReconciliation[]>;
+    twinReferenceReconciliation(instanceId: string, scope: string, context: ResolverContext): Promise<TwinReferenceReconciliation | null>;
+}

package/dist-server/service/reference/reference-reconciliation-query.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwinReferenceReconciliationQuery = void 0;
+const tslib_1 = require("tslib");
+const type_graphql_1 = require("type-graphql");
+const shell_1 = require("@things-factory/shell");
+const twin_reference_reconciliation_js_1 = require("./twin-reference-reconciliation.js");
+let TwinReferenceReconciliationQuery = class TwinReferenceReconciliationQuery {
+    async twinReferenceReconciliations(instanceId, context) {
+        return (0, shell_1.getRepository)(twin_reference_reconciliation_js_1.TwinReferenceReconciliation).find({
+            where: { domain: { id: context.state.domain.id }, instanceId },
+            order: { scope: 'ASC' }
+        });
+    }
+    async twinReferenceReconciliation(instanceId, scope, context) {
+        return (0, shell_1.getRepository)(twin_reference_reconciliation_js_1.TwinReferenceReconciliation).findOne({
+            where: { domain: { id: context.state.domain.id }, instanceId, scope }
+        });
+    }
+};
+exports.TwinReferenceReconciliationQuery = TwinReferenceReconciliationQuery;
+tslib_1.__decorate([
+    (0, type_graphql_1.Query)(returns => [twin_reference_reconciliation_js_1.TwinReferenceReconciliation], { description: 'All latest durable sequence reconciliations for one Twin. An empty list means no numbered source range has been read yet, not that every source is aligned.' }),
+    tslib_1.__param(0, (0, type_graphql_1.Arg)('instanceId')),
+    tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [String, Object]),
+    tslib_1.__metadata("design:returntype", Promise)
+], TwinReferenceReconciliationQuery.prototype, "twinReferenceReconciliations", null);
+tslib_1.__decorate([
+    (0, type_graphql_1.Query)(returns => twin_reference_reconciliation_js_1.TwinReferenceReconciliation, { nullable: true, description: 'Latest durable source-range versus Twin-cursor reconciliation for one numbered scope. Null means no backfill has yet obtained a source range; it is not an aligned result.' }),
+    tslib_1.__param(0, (0, type_graphql_1.Arg)('instanceId')),
+    tslib_1.__param(1, (0, type_graphql_1.Arg)('scope')),
+    tslib_1.__param(2, (0, type_graphql_1.Ctx)()),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [String, String, Object]),
+    tslib_1.__metadata("design:returntype", Promise)
+], TwinReferenceReconciliationQuery.prototype, "twinReferenceReconciliation", null);
+exports.TwinReferenceReconciliationQuery = TwinReferenceReconciliationQuery = tslib_1.__decorate([
+    (0, type_graphql_1.Resolver)()
+], TwinReferenceReconciliationQuery);
+//# sourceMappingURL=reference-reconciliation-query.js.map

package/dist-server/service/reference/reference-reconciliation-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-reconciliation-query.js","sourceRoot":"","sources":["../../../server/service/reference/reference-reconciliation-query.ts"],"names":[],"mappings":";;;;AAAA,+CAAwD;AACxD,iDAAqD;AACrD,yFAAgF;AAGzE,IAAM,gCAAgC,GAAtC,MAAM,gCAAgC;IAErC,AAAN,KAAK,CAAC,4BAA4B,CACb,UAAkB,EAC9B,OAAwB;QAE/B,OAAO,IAAA,qBAAa,EAAC,8DAA2B,CAAC,CAAC,IAAI,CAAC;YACrD,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,UAAU,EAAE;YAC9D,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;SACxB,CAAC,CAAA;IACJ,CAAC;IAGK,AAAN,KAAK,CAAC,2BAA2B,CACZ,UAAkB,EACvB,KAAa,EACpB,OAAwB;QAE/B,OAAO,IAAA,qBAAa,EAAC,8DAA2B,CAAC,CAAC,OAAO,CAAC;YACxD,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE;SACtE,CAAC,CAAA;IACJ,CAAC;CACF,CAAA;AAtBY,4EAAgC;AAErC;IADL,IAAA,oBAAK,EAAC,OAAO,CAAC,EAAE,CAAC,CAAC,8DAA2B,CAAC,EAAE,EAAE,WAAW,EAAE,6JAA6J,EAAE,CAAC;IAE7N,mBAAA,IAAA,kBAAG,EAAC,YAAY,CAAC,CAAA;IACjB,mBAAA,IAAA,kBAAG,GAAE,CAAA;;;;oFAMP;AAGK;IADL,IAAA,oBAAK,EAAC,OAAO,CAAC,EAAE,CAAC,8DAA2B,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,4KAA4K,EAAE,CAAC;IAE1P,mBAAA,IAAA,kBAAG,EAAC,YAAY,CAAC,CAAA;IACjB,mBAAA,IAAA,kBAAG,EAAC,OAAO,CAAC,CAAA;IACZ,mBAAA,IAAA,kBAAG,GAAE,CAAA;;;;mFAKP;2CArBU,gCAAgC;IAD5C,IAAA,uBAAQ,GAAE;GACE,gCAAgC,CAsB5C","sourcesContent":["import { Arg, Ctx, Query, Resolver } from 'type-graphql'\nimport { getRepository } from '@things-factory/shell'\nimport { TwinReferenceReconciliation } from './twin-reference-reconciliation.js'\n\n@Resolver()\nexport class TwinReferenceReconciliationQuery {\n  @Query(returns => [TwinReferenceReconciliation], { description: 'All latest durable sequence reconciliations for one Twin. An empty list means no numbered source range has been read yet, not that every source is aligned.' })\n  async twinReferenceReconciliations(\n    @Arg('instanceId') instanceId: string,\n    @Ctx() context: ResolverContext\n  ): Promise<TwinReferenceReconciliation[]> {\n    return getRepository(TwinReferenceReconciliation).find({\n      where: { domain: { id: context.state.domain.id }, instanceId },\n      order: { scope: 'ASC' }\n    })\n  }\n\n  @Query(returns => TwinReferenceReconciliation, { nullable: true, description: 'Latest durable source-range versus Twin-cursor reconciliation for one numbered scope. Null means no backfill has yet obtained a source range; it is not an aligned result.' })\n  async twinReferenceReconciliation(\n    @Arg('instanceId') instanceId: string,\n    @Arg('scope') scope: string,\n    @Ctx() context: ResolverContext\n  ): Promise<TwinReferenceReconciliation | null> {\n    return getRepository(TwinReferenceReconciliation).findOne({\n      where: { domain: { id: context.state.domain.id }, instanceId, scope }\n    })\n  }\n}\n"]}

package/dist-server/service/reference/reference-reconciliation-writer.d.ts

@@ -0,0 +1,10 @@
+import { type ReferenceRange } from './reference-reconciliation.js';
+/** backfill이 원본 범위를 실제로 읽은 뒤에만 최신 대사 상태를 갱신한다. */
+export declare function recordReferenceReconciliation(args: {
+    domainId: string;
+    instanceId: string;
+    scope: string;
+    sourceRange?: ReferenceRange;
+    cursorSeq?: number;
+    firstSeqSeen?: number;
+}): Promise<void>;

package/dist-server/service/reference/reference-reconciliation-writer.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordReferenceReconciliation = recordReferenceReconciliation;
+const shell_1 = require("@things-factory/shell");
+const twin_reference_reconciliation_js_1 = require("./twin-reference-reconciliation.js");
+const reference_reconciliation_js_1 = require("./reference-reconciliation.js");
+/** backfill이 원본 범위를 실제로 읽은 뒤에만 최신 대사 상태를 갱신한다. */
+async function recordReferenceReconciliation(args) {
+    const { domainId, instanceId, scope, sourceRange, cursorSeq, firstSeqSeen } = args;
+    if (!sourceRange)
+        return;
+    const verdict = (0, reference_reconciliation_js_1.reconcileReferenceSequence)({ source: sourceRange, cursorSeq, firstSeqSeen });
+    const repo = (0, shell_1.getRepository)(twin_reference_reconciliation_js_1.TwinReferenceReconciliation);
+    const previous = await repo.findOne({ where: { domain: { id: domainId }, instanceId, scope } });
+    await repo.save(repo.create({
+        ...(previous ?? {}),
+        domain: { id: domainId },
+        instanceId,
+        scope,
+        status: verdict.status,
+        /* TypeORM은 undefined를 "갱신하지 않음"으로 읽는다. 현재 대사가 맞아진 뒤 옛 gap 수가
+         * 남지 않게 nullable 칸은 명시적으로 null로 지운다. */
+        sourceFirst: verdict.sourceFirst ?? null,
+        sourceLast: verdict.sourceLast ?? null,
+        cursorSeq: verdict.cursorSeq ?? null,
+        firstSeqSeen: verdict.firstSeqSeen ?? null,
+        headMissing: verdict.headMissing ?? null,
+        behind: verdict.behind ?? null,
+        reason: verdict.reason ?? null,
+        checkedAt: new Date()
+    }));
+}
+//# sourceMappingURL=reference-reconciliation-writer.js.map

package/dist-server/service/reference/reference-reconciliation-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-reconciliation-writer.js","sourceRoot":"","sources":["../../../server/service/reference/reference-reconciliation-writer.ts"],"names":[],"mappings":";;AAKA,sEAgCC;AArCD,iDAAqD;AACrD,yFAAgF;AAChF,+EAA+F;AAE/F,kDAAkD;AAC3C,KAAK,UAAU,6BAA6B,CAAC,IAOnD;IACC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,IAAI,CAAA;IAClF,IAAI,CAAC,WAAW;QAAE,OAAM;IACxB,MAAM,OAAO,GAAG,IAAA,wDAA0B,EAAC,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,CAAA;IAC5F,MAAM,IAAI,GAAG,IAAA,qBAAa,EAAC,8DAA2B,CAAC,CAAA;IACvD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,CAAC,CAAA;IAC/F,MAAM,IAAI,CAAC,IAAI,CACb,IAAI,CAAC,MAAM,CAAC;QACV,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;QACnB,MAAM,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAS;QAC/B,UAAU;QACV,KAAK;QACL,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB;gDACwC;QACxC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;QACxC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI;QACtC,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI;QACpC,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,IAAI;QAC1C,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;QACxC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI;QAC9B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI;QAC9B,SAAS,EAAE,IAAI,IAAI,EAAE;KACtB,CAAC,CACH,CAAA;AACH,CAAC","sourcesContent":["import { getRepository } from '@things-factory/shell'\nimport { TwinReferenceReconciliation } from './twin-reference-reconciliation.js'\nimport { reconcileReferenceSequence, type ReferenceRange } from './reference-reconciliation.js'\n\n/** backfill이 원본 범위를 실제로 읽은 뒤에만 최신 대사 상태를 갱신한다. */\nexport async function recordReferenceReconciliation(args: {\n  domainId: string\n  instanceId: string\n  scope: string\n  sourceRange?: ReferenceRange\n  cursorSeq?: number\n  firstSeqSeen?: number\n}): Promise<void> {\n  const { domainId, instanceId, scope, sourceRange, cursorSeq, firstSeqSeen } = args\n  if (!sourceRange) return\n  const verdict = reconcileReferenceSequence({ source: sourceRange, cursorSeq, firstSeqSeen })\n  const repo = getRepository(TwinReferenceReconciliation)\n  const previous = await repo.findOne({ where: { domain: { id: domainId }, instanceId, scope } })\n  await repo.save(\n    repo.create({\n      ...(previous ?? {}),\n      domain: { id: domainId } as any,\n      instanceId,\n      scope,\n      status: verdict.status,\n      /* TypeORM은 undefined를 \"갱신하지 않음\"으로 읽는다. 현재 대사가 맞아진 뒤 옛 gap 수가\n       * 남지 않게 nullable 칸은 명시적으로 null로 지운다. */\n      sourceFirst: verdict.sourceFirst ?? null,\n      sourceLast: verdict.sourceLast ?? null,\n      cursorSeq: verdict.cursorSeq ?? null,\n      firstSeqSeen: verdict.firstSeqSeen ?? null,\n      headMissing: verdict.headMissing ?? null,\n      behind: verdict.behind ?? null,\n      reason: verdict.reason ?? null,\n      checkedAt: new Date()\n    })\n  )\n}\n"]}

package/dist-server/service/reference/reference-reconciliation.d.ts

@@ -0,0 +1,19 @@
+export type ReferenceRange = {
+    first?: number;
+    last?: number;
+};
+export type ReferenceReconciliation = {
+    sourceFirst?: number;
+    sourceLast?: number;
+    cursorSeq?: number;
+    firstSeqSeen?: number;
+    headMissing?: number;
+    behind?: number;
+    status: 'aligned' | 'gap' | 'unknown';
+    reason?: string;
+};
+export declare function reconcileReferenceSequence(args: {
+    source: ReferenceRange | undefined;
+    cursorSeq?: number;
+    firstSeqSeen?: number;
+}): ReferenceReconciliation;

package/dist-server/service/reference/reference-reconciliation.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconcileReferenceSequence = reconcileReferenceSequence;
+function reconcileReferenceSequence(args) {
+    const { source, cursorSeq, firstSeqSeen } = args;
+    const sourceFirst = source?.first;
+    const sourceLast = source?.last;
+    const base = { sourceFirst, sourceLast, cursorSeq, firstSeqSeen };
+    if (sourceFirst === undefined || sourceLast === undefined) {
+        return { ...base, status: 'unknown', reason: '원본이 번호 범위의 양 끝을 주지 않아 대사할 수 없습니다' };
+    }
+    if (cursorSeq === undefined) {
+        return { ...base, status: 'unknown', reason: 'Twin이 아직 이 단위의 번호를 받은 적이 없습니다' };
+    }
+    if (cursorSeq < sourceFirst) {
+        return {
+            ...base,
+            status: 'unknown',
+            reason: 'Twin 커서가 원본의 첫 번호보다 앞입니다. 원본 번호가 다시 매겨졌거나 다른 단위의 커서입니다'
+        };
+    }
+    const behind = Math.max(0, sourceLast - cursorSeq);
+    /* 처음 받은 번호를 적지 않았으면 앞머리는 "없음"이 아니라 "모름"이다. */
+    const headMissing = firstSeqSeen === undefined ? undefined : Math.max(0, firstSeqSeen - sourceFirst);
+    if (behind || headMissing) {
+        return { ...base, ...(behind ? { behind } : {}), ...(headMissing ? { headMissing } : {}), status: 'gap' };
+    }
+    if (firstSeqSeen === undefined) {
+        return { ...base, status: 'unknown', reason: '처음 받은 번호가 기록되지 않아 앞머리 연속성은 확인할 수 없습니다' };
+    }
+    return { ...base, status: 'aligned' };
+}
+//# sourceMappingURL=reference-reconciliation.js.map

package/dist-server/service/reference/reference-reconciliation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-reconciliation.js","sourceRoot":"","sources":["../../../server/service/reference/reference-reconciliation.ts"],"names":[],"mappings":";;AAoBA,gEAkCC;AAlCD,SAAgB,0BAA0B,CAAC,IAI1C;IACC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,IAAI,CAAA;IAChD,MAAM,WAAW,GAAG,MAAM,EAAE,KAAK,CAAA;IACjC,MAAM,UAAU,GAAG,MAAM,EAAE,IAAI,CAAA;IAC/B,MAAM,IAAI,GAAG,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,CAAA;IAEjE,IAAI,WAAW,KAAK,SAAS,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC1D,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,kCAAkC,EAAE,CAAA;IACnF,CAAC;IACD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,+BAA+B,EAAE,CAAA;IAChF,CAAC;IACD,IAAI,SAAS,GAAG,WAAW,EAAE,CAAC;QAC5B,OAAO;YACL,GAAG,IAAI;YACP,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,wDAAwD;SACjE,CAAA;IACH,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,CAAA;IAClD,8CAA8C;IAC9C,MAAM,WAAW,GAAG,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,GAAG,WAAW,CAAC,CAAA;IACpG,IAAI,MAAM,IAAI,WAAW,EAAE,CAAC;QAC1B,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;IAC3G,CAAC;IACD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,uCAAuC,EAAE,CAAA;IACxF,CAAC;IACD,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAA;AACvC,CAAC","sourcesContent":["/*\n * 원본 번호 범위와 Twin 커서를 맞춘 **현재 판정**이다.\n *\n * 이 계산은 봉투 수와 저널 행 수를 비교하지 않는다. 재전송과 backfill 때문에 그 둘은 같은\n * 사실을 여러 번 셀 수 있다. 여기서 답하는 것은 번호를 매기는 원본에서만 가능한, 더 좁고\n * 검증 가능한 질문이다: \"원본의 양 끝과 우리가 처음/마지막으로 받은 번호가 이어지는가?\"\n */\nexport type ReferenceRange = { first?: number; last?: number }\n\nexport type ReferenceReconciliation = {\n  sourceFirst?: number\n  sourceLast?: number\n  cursorSeq?: number\n  firstSeqSeen?: number\n  headMissing?: number\n  behind?: number\n  status: 'aligned' | 'gap' | 'unknown'\n  reason?: string\n}\n\nexport function reconcileReferenceSequence(args: {\n  source: ReferenceRange | undefined\n  cursorSeq?: number\n  firstSeqSeen?: number\n}): ReferenceReconciliation {\n  const { source, cursorSeq, firstSeqSeen } = args\n  const sourceFirst = source?.first\n  const sourceLast = source?.last\n  const base = { sourceFirst, sourceLast, cursorSeq, firstSeqSeen }\n\n  if (sourceFirst === undefined || sourceLast === undefined) {\n    return { ...base, status: 'unknown', reason: '원본이 번호 범위의 양 끝을 주지 않아 대사할 수 없습니다' }\n  }\n  if (cursorSeq === undefined) {\n    return { ...base, status: 'unknown', reason: 'Twin이 아직 이 단위의 번호를 받은 적이 없습니다' }\n  }\n  if (cursorSeq < sourceFirst) {\n    return {\n      ...base,\n      status: 'unknown',\n      reason: 'Twin 커서가 원본의 첫 번호보다 앞입니다. 원본 번호가 다시 매겨졌거나 다른 단위의 커서입니다'\n    }\n  }\n\n  const behind = Math.max(0, sourceLast - cursorSeq)\n  /* 처음 받은 번호를 적지 않았으면 앞머리는 \"없음\"이 아니라 \"모름\"이다. */\n  const headMissing = firstSeqSeen === undefined ? undefined : Math.max(0, firstSeqSeen - sourceFirst)\n  if (behind || headMissing) {\n    return { ...base, ...(behind ? { behind } : {}), ...(headMissing ? { headMissing } : {}), status: 'gap' }\n  }\n  if (firstSeqSeen === undefined) {\n    return { ...base, status: 'unknown', reason: '처음 받은 번호가 기록되지 않아 앞머리 연속성은 확인할 수 없습니다' }\n  }\n  return { ...base, status: 'aligned' }\n}\n"]}

package/dist-server/service/reference/twin-reference-reconciliation.d.ts

@@ -0,0 +1,19 @@
+import { Domain } from '@things-factory/shell';
+export declare class TwinReferenceReconciliation {
+    readonly id: string;
+    domain?: Domain;
+    domainId?: string;
+    instanceId: string;
+    scope: string;
+    status: 'aligned' | 'gap' | 'unknown';
+    sourceFirst?: number;
+    sourceLast?: number;
+    cursorSeq?: number;
+    firstSeqSeen?: number;
+    headMissing?: number;
+    behind?: number;
+    reason?: string;
+    checkedAt: Date;
+    createdAt?: Date;
+    updatedAt?: Date;
+}

package/dist-server/service/reference/twin-reference-reconciliation.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwinReferenceReconciliation = void 0;
+const tslib_1 = require("tslib");
+const typeorm_1 = require("typeorm");
+const type_graphql_1 = require("type-graphql");
+const shell_1 = require("@things-factory/shell");
+/* 한 연결·Twin·단위의 최신 번호 대사 상태. 과거 추이는 ingest window가, 현재 조치 판단은 이 표가 답한다. */
+let TwinReferenceReconciliation = class TwinReferenceReconciliation {
+};
+exports.TwinReferenceReconciliation = TwinReferenceReconciliation;
+tslib_1.__decorate([
+    (0, typeorm_1.PrimaryGeneratedColumn)('uuid'),
+    (0, type_graphql_1.Field)(type => type_graphql_1.ID),
+    tslib_1.__metadata("design:type", String)
+], TwinReferenceReconciliation.prototype, "id", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.ManyToOne)(type => shell_1.Domain),
+    (0, type_graphql_1.Field)(type => shell_1.Domain, { nullable: true }),
+    tslib_1.__metadata("design:type", shell_1.Domain)
+], TwinReferenceReconciliation.prototype, "domain", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.RelationId)((e) => e.domain),
+    tslib_1.__metadata("design:type", String)
+], TwinReferenceReconciliation.prototype, "domainId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)(),
+    tslib_1.__metadata("design:type", String)
+], TwinReferenceReconciliation.prototype, "instanceId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)(),
+    tslib_1.__metadata("design:type", String)
+], TwinReferenceReconciliation.prototype, "scope", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)(),
+    tslib_1.__metadata("design:type", String)
+], TwinReferenceReconciliation.prototype, "status", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int', nullable: true }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.Int, { nullable: true }),
+    tslib_1.__metadata("design:type", Number)
+], TwinReferenceReconciliation.prototype, "sourceFirst", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int', nullable: true }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.Int, { nullable: true }),
+    tslib_1.__metadata("design:type", Number)
+], TwinReferenceReconciliation.prototype, "sourceLast", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int', nullable: true }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.Int, { nullable: true }),
+    tslib_1.__metadata("design:type", Number)
+], TwinReferenceReconciliation.prototype, "cursorSeq", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int', nullable: true }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.Int, { nullable: true }),
+    tslib_1.__metadata("design:type", Number)
+], TwinReferenceReconciliation.prototype, "firstSeqSeen", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int', nullable: true }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.Int, { nullable: true }),
+    tslib_1.__metadata("design:type", Number)
+], TwinReferenceReconciliation.prototype, "headMissing", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int', nullable: true }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.Int, { nullable: true }),
+    tslib_1.__metadata("design:type", Number)
+], TwinReferenceReconciliation.prototype, "behind", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true }),
+    tslib_1.__metadata("design:type", String)
+], TwinReferenceReconciliation.prototype, "reason", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)(),
+    tslib_1.__metadata("design:type", Date)
+], TwinReferenceReconciliation.prototype, "checkedAt", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.CreateDateColumn)(),
+    tslib_1.__metadata("design:type", Date)
+], TwinReferenceReconciliation.prototype, "createdAt", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.UpdateDateColumn)(),
+    tslib_1.__metadata("design:type", Date)
+], TwinReferenceReconciliation.prototype, "updatedAt", void 0);
+exports.TwinReferenceReconciliation = TwinReferenceReconciliation = tslib_1.__decorate([
+    (0, typeorm_1.Entity)(),
+    (0, typeorm_1.Index)('uq_twin_reference_reconciliation_0', (e) => [e.domain, e.instanceId, e.scope], { unique: true }),
+    (0, typeorm_1.Index)('ix_twin_reference_reconciliation_0', (e) => [e.domain, e.instanceId, e.checkedAt], { unique: false }),
+    (0, type_graphql_1.ObjectType)({ description: 'Latest durable sequence reconciliation for one connected source scope. It reports only what numbered source ranges can prove; it never substitutes replay-prone ingest-window counts for source facts.' })
+], TwinReferenceReconciliation);
+//# sourceMappingURL=twin-reference-reconciliation.js.map

package/dist-server/service/reference/twin-reference-reconciliation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twin-reference-reconciliation.js","sourceRoot":"","sources":["../../../server/service/reference/twin-reference-reconciliation.ts"],"names":[],"mappings":"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","sourcesContent":["import { Column, CreateDateColumn, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId, UpdateDateColumn } from 'typeorm'\nimport { Field, ID, Int, ObjectType } from 'type-graphql'\nimport { Domain } from '@things-factory/shell'\n\n/* 한 연결·Twin·단위의 최신 번호 대사 상태. 과거 추이는 ingest window가, 현재 조치 판단은 이 표가 답한다. */\n@Entity()\n@Index('uq_twin_reference_reconciliation_0', (e: TwinReferenceReconciliation) => [e.domain, e.instanceId, e.scope], { unique: true })\n@Index('ix_twin_reference_reconciliation_0', (e: TwinReferenceReconciliation) => [e.domain, e.instanceId, e.checkedAt], { unique: false })\n@ObjectType({ description: 'Latest durable sequence reconciliation for one connected source scope. It reports only what numbered source ranges can prove; it never substitutes replay-prone ingest-window counts for source facts.' })\nexport class TwinReferenceReconciliation {\n  @PrimaryGeneratedColumn('uuid') @Field(type => ID) readonly id: string\n  @ManyToOne(type => Domain) @Field(type => Domain, { nullable: true }) domain?: Domain\n  @RelationId((e: TwinReferenceReconciliation) => e.domain) domainId?: string\n  @Column() @Field() instanceId: string\n  @Column() @Field() scope: string\n  @Column() @Field() status: 'aligned' | 'gap' | 'unknown'\n  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) sourceFirst?: number\n  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) sourceLast?: number\n  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) cursorSeq?: number\n  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) firstSeqSeen?: number\n  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) headMissing?: number\n  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) behind?: number\n  @Column({ nullable: true }) @Field({ nullable: true }) reason?: string\n  @Column() @Field() checkedAt: Date\n  @CreateDateColumn() createdAt?: Date\n  @UpdateDateColumn() updatedAt?: Date\n}\n"]}

package/dist-server/service/twin-lifecycle/twin-lifecycle-mutation.d.ts

@@ -1,6 +1,9 @@
 export declare class TwinLifecycleMutation {
     /** 기동 — model 를 주면 provision+start, 없으면 레지스트리에 저장된 구조로 start. */
-    startTwinInstance(instanceId: string, context: ResolverContext, kind?: string, model?: any): Promise<boolean>;
+    startTwinInstance(instanceId: string, context: ResolverContext, kind?: string, model?: any, 
+    /** 새 시뮬레이션은 재기동 때 저널을 이어야 한다. 엔진에는 이미 필수지만 이 API가 누락해
+     * zero-to-twin 경로가 기동 단계에서 막혔다. */
+    restartPolicy?: 'resync' | 'resume' | 'reset'): Promise<boolean>;
     stopTwinInstance(instanceId: string, context: ResolverContext): Promise<boolean>;
     /**
      * 이 트윈이 **자기 과거를 어떻게 대할 것인가**를 다시 선언한다 (2026-08-20).
@@ -42,6 +45,15 @@ export declare class TwinLifecycleMutation {
      * 그것을 「이름을 바꿨다」로 보고하면 거짓이다. 지우고 싶으면 그 뜻의 문이 따로 있어야 한다.
      */
     renameTwinInstance(instanceId: string, name: string, context: ResolverContext): Promise<any>;
+    /**
+     * 폐기 전에 사라질 것을 읽는다.
+     *
+     * 삭제는 레지스트리 행 하나만 없애는 일이 아니다. `TwinEngine.remove` 는 같은 트윈의 저널도
+     * purge 한다. 그래서 확인 창이 추측한 숫자를 쓰지 않고, **삭제와 같은 domain·instance 범위**를
+     * 직접 센다. 저널이 비어 있는 트윈도 `0` 과 null 기간을 돌려준다 — 없는 기록을 기간으로
+     * 꾸며내면 "아무것도 안 지워진다"와 "언제부터인지 모른다"가 섞인다.
+     */
+    twinDeletionPreview(instanceId: string, context: ResolverContext): Promise<any | null>;
     /** 삭제 — 정지 + 레지스트리 삭제 + 저널 purge(domain 스코프). */
     deleteTwinInstance(instanceId: string, context: ResolverContext): Promise<boolean>;
     /** 관리 목록 — 등록된 인스턴스 전체(kind/status/running/revision/노드·무버 수). 데이터 없으면 빈 배열. */

package/dist-server/service/twin-lifecycle/twin-lifecycle-mutation.js

@@ -8,6 +8,7 @@ const index_js_1 = require("../../engine/index.js");
 /* 정책 읽기는 그 모듈에서 직접 가져온다 — 다른 소비처(`reference-resolver`)와 같은 길이다. */
 const restart_policy_js_1 = require("../../engine/restart-policy.js");
 const twin_instance_js_1 = require("../twin-instance/twin-instance.js");
+const twin_event_js_1 = require("../twin-event/twin-event.js");
 /* 도메인 어휘 카탈로그(시스템별 노드 타입) — 커널이 SSOT. 앱/UI 는 이걸 소싱하고 재선언하지 않는다(방언 금지).
  * 조합은 domain-catalog.ts 가 소유 — 리졸버와 서버측 소비자(board-ai 도구 등)가 같은 형태를 본다. */
 const domain_catalog_js_1 = require("./domain-catalog.js");
@@ -30,7 +31,7 @@ let TwinLifecycleMutation = class TwinLifecycleMutation {
      * 트윈을 고치는 쪽이 아니다(ADR-0029 — 시뮬레이터는 원본의 한 종류).
      */
     /** 기동 — model 를 주면 provision+start, 없으면 레지스트리에 저장된 구조로 start. */
-    async startTwinInstance(instanceId, context, kind, model) {
+    async startTwinInstance(instanceId, context, kind, model, restartPolicy) {
         const domainId = context.state.domain.id;
         // 시각 기준은 **공간**이 갖는다(테넌트 아님) — 교대의 HH:MM 을 어느 기준으로 읽나.
         if (model) {
@@ -38,7 +39,7 @@ let TwinLifecycleMutation = class TwinLifecycleMutation {
                예전에는 `kind ?? 'wms'` 로 메웠는데, 종류를 빠뜨린 야드/생산 트윈이 **창고로 알리지 않고 기동**했다. */
             if (!kind)
                 throw new Error('kind is required when model is given — it decides which domain kernel runs this twin');
-            index_js_1.TwinEngine.start(instanceId, domainId, kind, await index_js_1.TwinEngine.withSpaceTimeBase(model, domainId));
+            index_js_1.TwinEngine.start(instanceId, domainId, kind, await index_js_1.TwinEngine.withSpaceTimeBase(model, domainId), restartPolicy);
         }
         else
             await index_js_1.TwinEngine.startFromRegistry(domainId, instanceId);
@@ -120,6 +121,35 @@ let TwinLifecycleMutation = class TwinLifecycleMutation {
         /* 도는 런타임은 이름을 쓰지 않는다(식별자로 돈다) — 그래서 정지·기동이 필요하지 않다. */
         return { instanceId, name: next, previous: before || null, changed: true };
     }
+    /**
+     * 폐기 전에 사라질 것을 읽는다.
+     *
+     * 삭제는 레지스트리 행 하나만 없애는 일이 아니다. `TwinEngine.remove` 는 같은 트윈의 저널도
+     * purge 한다. 그래서 확인 창이 추측한 숫자를 쓰지 않고, **삭제와 같은 domain·instance 범위**를
+     * 직접 센다. 저널이 비어 있는 트윈도 `0` 과 null 기간을 돌려준다 — 없는 기록을 기간으로
+     * 꾸며내면 "아무것도 안 지워진다"와 "언제부터인지 모른다"가 섞인다.
+     */
+    async twinDeletionPreview(instanceId, context) {
+        const domainId = context.state.domain.id;
+        const instance = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } });
+        if (!instance)
+            return null;
+        const journal = await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent)
+            .createQueryBuilder('event')
+            .select('COUNT(event.id)', 'count')
+            .addSelect('MIN(event.eventTime)', 'firstEventAt')
+            .addSelect('MAX(event.eventTime)', 'lastEventAt')
+            .where('event.domain = :domainId', { domainId })
+            .andWhere('event.instanceId = :instanceId', { instanceId })
+            .getRawOne();
+        return {
+            instanceId,
+            name: instance.name ?? null,
+            journalCount: Number(journal?.count ?? 0),
+            firstEventAt: journal?.firstEventAt ?? null,
+            lastEventAt: journal?.lastEventAt ?? null
+        };
+    }
     /** 삭제 — 정지 + 레지스트리 삭제 + 저널 purge(domain 스코프). */
     async deleteTwinInstance(instanceId, context) {
         await index_js_1.TwinEngine.remove(context.state.domain.id, instanceId);
@@ -194,8 +224,9 @@ tslib_1.__decorate([
     tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
     tslib_1.__param(2, (0, type_graphql_1.Arg)('kind', { nullable: true })),
     tslib_1.__param(3, (0, type_graphql_1.Arg)('model', type => shell_1.ScalarObject, { nullable: true })),
+    tslib_1.__param(4, (0, type_graphql_1.Arg)('restartPolicy', { nullable: true })),
     tslib_1.__metadata("design:type", Function),
-    tslib_1.__metadata("design:paramtypes", [String, Object, String, Object]),
+    tslib_1.__metadata("design:paramtypes", [String, Object, String, Object, String]),
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinLifecycleMutation.prototype, "startTwinInstance", null);
 tslib_1.__decorate([
@@ -234,6 +265,17 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:paramtypes", [String, String, Object]),
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinLifecycleMutation.prototype, "renameTwinInstance", null);
+tslib_1.__decorate([
+    (0, type_graphql_1.Query)(returns => shell_1.ScalarObject, {
+        nullable: true,
+        description: 'Describe what deleting one twin would purge before it is deleted: its registry identity and the count plus first/last event time of its journal. Null means this twin is not in the current domain.'
+    }),
+    tslib_1.__param(0, (0, type_graphql_1.Arg)('instanceId')),
+    tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [String, Object]),
+    tslib_1.__metadata("design:returntype", Promise)
+], TwinLifecycleMutation.prototype, "twinDeletionPreview", null);
 tslib_1.__decorate([
     (0, type_graphql_1.Directive)('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)'),
     (0, type_graphql_1.Mutation)(returns => Boolean, { description: 'Delete a twin instance: stop it, remove the registry entry and purge its event journal.' }),