@things-factory/headless-twin 10.0.18 → 10.1.0

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

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fillSince = fillSince;
+/*
+ * **놓친 구간을 backfill 해 채운다** — 밀어 받는 길의 짝.
+ *
+ * ── 왜 필요한가 (2026-08-31, 인티그레이션 레인 지적) ──────────────────────
+ * 훅은 반드시 놓친다 — 우리가 내려가 있을 때, 그쪽이 못 보냈을 때, 네트워크가 끊겼을 때. 받는 쪽이
+ * 번호로 그것을 **알아채게** 되었지만(§`takeInSequence`), 알아챈 뒤 **그 사이를 채우는 길이 없었다.**
+ * 설계가 그 길을 적어 두었는데 만들지 않았다.
+ *
+ * ── 같은 검사를 지난다 ───────────────────────────────────────────────────
+ * backfill 한 것도 `takeInSequence` 를 지난다. 여기서 따로 만들면 두 길이 다른 규칙으로 받고, 한쪽만
+ * 고쳐지는 날 어긋난 그 길에서만 사실이 사라진다.
+ *
+ * ── 멈추는 조건을 셋 둔다 ────────────────────────────────────────────────
+ * 되풀이해서 요청하는 경로는 **끝나지 않는 것**이 가장 흔한 결함이다.
+ *
+ *   빈 답        더 줄 것이 없다. 끝
+ *   번호가 안 나아간다  같은 것을 다시 받았다 — 무한히 요청하는 것을 막는다
+ *   구멍         원본의 아웃박스에 구멍이 있다. 이어 받으면 커서가 그 번호를 지나쳐 적힌다
+ *
+ * 그리고 **쪽 상한**을 둔다. 상한에 닿았으면 조용히 끝내지 않고 말한다 — 조용히 자르면 사람은 다 받은
+ * 줄로 읽는다.
+ */
+const hook_contract_js_1 = require("./hook-contract.js");
+const log_js_1 = require("../../engine/log.js");
+/** 몇 쪽까지 받나 — 한 번의 채우기가 서버를 오래 붙잡지 않게. */
+const MAX_PAGES = 50;
+/**
+ * 그 단위의 놓친 구간을 채운다.
+ *
+ * `ingest` 를 부르는 쪽이 넘겨 준다 — 훅과 같은 이유다(이 파일이 엔진을 직접 부르면 시험이 엔진을
+ * 세워야 한다).
+ */
+async function fillSince(args) {
+    const { cfg, site, scope, cursorKey, fetch, ingest, saveCursor, beforeIngest } = args;
+    const maxPages = args.maxPages ?? MAX_PAGES;
+    let cursor = args.cursor;
+    let applied = 0;
+    let duplicates = 0;
+    let rejectedCount = 0;
+    const rejectedReasons = {};
+    let vocabulary = 0;
+    const undated = {};
+    /* 원본이 말한 번호 범위 — 마지막으로 받은 묶음의 것을 들고 나간다. 안 말하면 끝까지 없다. */
+    let sourceRange;
+    /* 이 실행에서 가장 낮게 받아들인 번호 — 커서에 firstSeq 로 적는다. */
+    let lowestSeq;
+    let pages = 0;
+    for (; pages < maxPages; pages++) {
+        const since = (0, hook_contract_js_1.seqOf)(cursor, cursorKey) ?? 0;
+        let batch;
+        try {
+            batch = await fetch(cfg, site, scope, since);
+        }
+        catch (e) {
+            return { applied, duplicates, rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}), vocabulary, ...(Object.keys(undated).length ? { undated } : {}), pages, ...seqPart(cursor, cursorKey), ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}), stopped: 'refused', detail: String(e?.message ?? e) };
+        }
+        if (batch?.sourceRange)
+            sourceRange = batch.sourceRange;
+        const items = batch?.items ?? [];
+        /* 빈 답은 더 줄 것이 없다는 뜻이다. 오류가 아니다. */
+        if (!items.length)
+            return { applied, duplicates, rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}), vocabulary, ...(Object.keys(undated).length ? { undated } : {}), pages, ...seqPart(cursor, cursorKey), ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}), stopped: 'done' };
+        const taken = (0, hook_contract_js_1.takeInSequence)({ items, scope, lastSeq: (0, hook_contract_js_1.seqOf)(cursor, cursorKey) });
+        if (taken.refused) {
+            return { applied, duplicates, rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}), vocabulary, ...(Object.keys(undated).length ? { undated } : {}), pages, ...seqPart(cursor, cursorKey), ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}), stopped: 'refused', detail: taken.refused };
+        }
+        if (taken.records.length) {
+            if (beforeIngest) {
+                await beforeIngest(taken.records).catch(e => (0, log_js_1.twinWarn)(`[twin-fill] 중복 판정 기억을 못 채웠다 — ${String(e?.message ?? e)}. 넣기는 그대로 간다`));
+            }
+            const result = ingest(taken.records);
+            applied += result.applied;
+            duplicates += result.duplicates ?? 0;
+            rejectedCount += result.rejected?.length ?? 0;
+            for (const r of result.rejected ?? []) {
+                /* 사유가 여럿이면 첫 줄로 묶는다 — 뒤는 대개 같은 원인의 곁가지다. */
+                const why = String(r?.errors?.[0] ?? '(사유 없음)').slice(0, 120);
+                rejectedReasons[why] = (rejectedReasons[why] ?? 0) + 1;
+            }
+            vocabulary += result.vocabulary ?? 0;
+            for (const [k, n] of Object.entries(result.undated ?? {}))
+                undated[k] = (undated[k] ?? 0) + n;
+        }
+        /*
+         * **번호가 나아가야 다음 쪽을 요청한다.** 원본이 빈 묶음에 물어본 번호를 그대로 돌려주는 계약이면,
+         * 나아감을 보지 않고 요청하면 무한히 돈다.
+         */
+        if (taken.advancedSeq === undefined || taken.advancedSeq <= since) {
+            if (taken.gap)
+                return { applied, duplicates, rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}), vocabulary, ...(Object.keys(undated).length ? { undated } : {}), pages: pages + 1, ...seqPart(cursor, cursorKey), ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}), stopped: 'gap', detail: gapWord(taken.gap) };
+            return {
+                applied,
+                duplicates,
+                rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}),
+                vocabulary,
+                ...(Object.keys(undated).length ? { undated } : {}),
+                pages: pages + 1,
+                ...seqPart(cursor, cursorKey),
+                ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}),
+                stopped: 'no-progress',
+                detail: `번호가 ${since} 에서 나아가지 않았다 — 같은 것을 다시 받았다`
+            };
+        }
+        if (lowestSeq === undefined)
+            lowestSeq = taken.lowestSeq;
+        /* 밑에서부터 다시 받았으면 그 번호가 곧 우리가 가진 가장 낮은 번호다. */
+        cursor = (0, hook_contract_js_1.withSeq)(cursor, cursorKey, taken.advancedSeq, taken.firstSeq ?? lowestSeq);
+        await saveCursor(cursor).catch(err => (0, log_js_1.twinWarn)(`[twin-fill] 번호를 커서에 적지 못했다 (${cursorKey}=${taken.advancedSeq}) — ${err?.message ?? err}`));
+        /*
+         * **구멍이 있으면 멈춘다.** 원본의 아웃박스에 구멍이 있는 것이고, 이어 받으면 커서가 그 번호를
+         * 지나쳐 적혀 빠진 사실이 다시 오지 않는다.
+         */
+        if (taken.gap) {
+            return { applied, duplicates, rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}), vocabulary, ...(Object.keys(undated).length ? { undated } : {}), pages: pages + 1, ...seqPart(cursor, cursorKey), ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}), stopped: 'gap', detail: gapWord(taken.gap) };
+        }
+    }
+    /* 상한에 닿았다 — 조용히 끝내지 않는다. 사람이 다 받은 줄로 읽으면 안 된다. */
+    return {
+        applied,
+        duplicates,
+        rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}),
+        vocabulary,
+        ...(Object.keys(undated).length ? { undated } : {}),
+        pages,
+        ...seqPart(cursor, cursorKey),
+        ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}),
+        stopped: 'page-limit',
+        detail: `${maxPages}쪽까지 받고 멈췄다 — 남은 것이 있을 수 있다. 다음 주기가 이어 받는다`
+    };
+}
+function seqPart(cursor, key) {
+    const seq = (0, hook_contract_js_1.seqOf)(cursor, key);
+    return seq === undefined ? {} : { lastSeq: seq };
+}
+function gapWord(gap) {
+    return `번호가 비었다 — ${gap.lastSeq} 다음이 ${gap.expectedSeq} 이어야 한다. 원본의 아웃박스에 구멍이 있다`;
+}
+//# sourceMappingURL=reference-fill.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reference-fill.js","sourceRoot":"","sources":["../../../server/service/reference/reference-fill.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * **놓친 구간을 backfill 해 채운다** — 밀어 받는 길의 짝.\n *\n * ── 왜 필요한가 (2026-08-31, 인티그레이션 레인 지적) ──────────────────────\n * 훅은 반드시 놓친다 — 우리가 내려가 있을 때, 그쪽이 못 보냈을 때, 네트워크가 끊겼을 때. 받는 쪽이\n * 번호로 그것을 **알아채게** 되었지만(§`takeInSequence`), 알아챈 뒤 **그 사이를 채우는 길이 없었다.**\n * 설계가 그 길을 적어 두었는데 만들지 않았다.\n *\n * ── 같은 검사를 지난다 ───────────────────────────────────────────────────\n * backfill 한 것도 `takeInSequence` 를 지난다. 여기서 따로 만들면 두 길이 다른 규칙으로 받고, 한쪽만\n * 고쳐지는 날 어긋난 그 길에서만 사실이 사라진다.\n *\n * ── 멈추는 조건을 셋 둔다 ────────────────────────────────────────────────\n * 되풀이해서 요청하는 경로는 **끝나지 않는 것**이 가장 흔한 결함이다.\n *\n *   빈 답        더 줄 것이 없다. 끝\n *   번호가 안 나아간다  같은 것을 다시 받았다 — 무한히 요청하는 것을 막는다\n *   구멍         원본의 아웃박스에 구멍이 있다. 이어 받으면 커서가 그 번호를 지나쳐 적힌다\n *\n * 그리고 **쪽 상한**을 둔다. 상한에 닿았으면 조용히 끝내지 않고 말한다 — 조용히 자르면 사람은 다 받은\n * 줄로 읽는다.\n */\nimport { seqOf, takeInSequence, withSeq } from './hook-contract.js'\nimport type { InboundBatch } from './reference-adapter.js'\nimport { twinWarn } from '../../engine/log.js'\n\n/** 한 번 채우고 나서 남는 사실. */\nexport interface FillOutcome {\n  /** 트윈에 넣은 레코드 수. */\n  applied: number\n  /**\n   * ingest 가 낸 네 갈래의 합 — **두 갈래로는 셈이 안 닫힌다.**\n   *\n   * ```\n   * 두 갈래   157 − 46 − 2 = 109 「설명 못 함」   진실은 되풀이 108 + 어휘 1\n   * 네 갈래   157 − 46 − 2 − 108 − 1 = 0\n   * ```\n   *\n   * 이 값이 없으면 원본 쪽에서 「보낸 것 20개 중 event 가 9개인데 나머지는 어디 갔나」를 셀 수\n   * 없다. 실제로 인티그레이션 레인이 그것을 물었고, 그 수가 트윈에 저장되지 않아 답을 못 했다.\n   */\n  duplicates: number\n  rejected: number\n  /**\n   * 왜 거절됐나 — **사유별 수.** 수만 내면 「26건이 안 들어온다」에서 멈춘다.\n   *\n   * 목록 전체가 아니라 사유별로 센다. 같은 이유로 거절된 26건이 26줄이면 읽는 사람이 그 줄을\n   * 세어야 하고, 다른 이유 하나가 그 안에 묻힌다.\n   */\n  rejectedReasons?: Record<string, number>\n  vocabulary: number\n  /** 시각을 못 읽어 ingest 시각으로 떨어진 것 — 종류별. 비어 있으면 전부 자기 시각을 말했다. */\n  undated?: Record<string, number>\n  /** 몇 쪽을 받았나. */\n  pages: number\n  /** 커서가 어디까지 갔나 — 아무것도 못 받았으면 없다. */\n  lastSeq?: number\n  /**\n   * 이 실행에서 **가장 낮게 받아들인 번호** — 밑에서부터 다시 받았을 때 이것이 곧 「우리가 가진\n   * 가장 낮은 번호」다.\n   */\n  lowestSeq?: number\n  /** 왜 멈췄나 — `done` · `gap` · `no-progress` · `page-limit` · `refused`. */\n  stopped: 'done' | 'gap' | 'no-progress' | 'page-limit' | 'refused'\n  /** 멈춘 이유의 사람 말. 알리지 않고 끝내지 않는다. */\n  detail?: string\n  /**\n   * 마지막으로 받은 묶음이 말한 **원본의 번호 범위** — 원본이 안 말하면 없다.\n   *\n   * 우리 커서와 견주는 자리가 이 값을 쓴다. 없으면 「맞다」가 아니라 **「모른다」**로 답해야 한다.\n   */\n  sourceRange?: { first?: number; last?: number }\n}\n\n/** 몇 쪽까지 받나 — 한 번의 채우기가 서버를 오래 붙잡지 않게. */\nconst MAX_PAGES = 50\n\n/**\n * 그 단위의 놓친 구간을 채운다.\n *\n * `ingest` 를 부르는 쪽이 넘겨 준다 — 훅과 같은 이유다(이 파일이 엔진을 직접 부르면 시험이 엔진을\n * 세워야 한다).\n */\nexport async function fillSince(args: {\n  cfg: Record<string, any>\n  site: { siteId: string }\n  /** 번호를 매기는 단위 — 커서 열쇠의 절반. 커넥터가 만들지 않는다. */\n  scope: string\n  /** 커서에 적힌 열쇠 — `pushCursorKey(instanceId, scope)`. */\n  cursorKey: string\n  /** 지금 커서 — 이 함수가 읽고, 나아간 만큼 되돌려 준다. */\n  cursor: unknown\n  fetch: (cfg: Record<string, any>, site: { siteId: string }, scope: string, since: number) => Promise<InboundBatch>\n  ingest: (records: unknown[]) => { applied: number; duplicates: number; rejected: unknown[] }\n  /**\n   * 넣기 **직전에** 부른다 — 이 쪽의 레코드를 넘긴다.\n   *\n   * 중복 판정 기억을 저널에서 채우는 자리다(§`fill-dedupe.ts`). 그 기억은 프로세스 안에만 있어서\n   * 재기동하면 비워지고, 그러면 이미 저널에 있는 사실도 「처음 본 것」이 된다.\n   *\n   * `ingest` 는 동기라 여기서 채울 수 없다. 이 훅은 비동기이므로 저널을 읽을 수 있다.\n   *\n   * 실패해도 넣기를 멈추지 않는다 — 기억을 못 채운 것이 사실을 못 받을 이유는 아니다.\n   */\n  beforeIngest?: (records: unknown[]) => Promise<void>\n  saveCursor: (cursor: Record<string, unknown>) => Promise<void>\n  maxPages?: number\n}): Promise<FillOutcome> {\n  const { cfg, site, scope, cursorKey, fetch, ingest, saveCursor , beforeIngest } = args\n  const maxPages = args.maxPages ?? MAX_PAGES\n\n  let cursor = args.cursor\n  let applied = 0\n  let duplicates = 0\n  let rejectedCount = 0\n  const rejectedReasons: Record<string, number> = {}\n  let vocabulary = 0\n  const undated: Record<string, number> = {}\n  /* 원본이 말한 번호 범위 — 마지막으로 받은 묶음의 것을 들고 나간다. 안 말하면 끝까지 없다. */\n  let sourceRange: { first?: number; last?: number } | undefined\n  /* 이 실행에서 가장 낮게 받아들인 번호 — 커서에 firstSeq 로 적는다. */\n  let lowestSeq: number | undefined\n  let pages = 0\n\n  for (; pages < maxPages; pages++) {\n    const since = seqOf(cursor, cursorKey) ?? 0\n\n    let batch: InboundBatch\n    try {\n      batch = await fetch(cfg, site, scope, since)\n    } catch (e: any) {\n      return { applied, duplicates, rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}), vocabulary, ...(Object.keys(undated).length ? { undated } : {}), pages, ...seqPart(cursor, cursorKey), ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}), stopped: 'refused', detail: String(e?.message ?? e) }\n    }\n\n    if (batch?.sourceRange) sourceRange = batch.sourceRange\n\n    const items = batch?.items ?? []\n    /* 빈 답은 더 줄 것이 없다는 뜻이다. 오류가 아니다. */\n    if (!items.length) return { applied, duplicates, rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}), vocabulary, ...(Object.keys(undated).length ? { undated } : {}), pages, ...seqPart(cursor, cursorKey), ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}), stopped: 'done' }\n\n    const taken = takeInSequence({ items, scope, lastSeq: seqOf(cursor, cursorKey) })\n    if (taken.refused) {\n      return { applied, duplicates, rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}), vocabulary, ...(Object.keys(undated).length ? { undated } : {}), pages, ...seqPart(cursor, cursorKey), ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}), stopped: 'refused', detail: taken.refused }\n    }\n\n    if (taken.records.length) {\n      if (beforeIngest) {\n        await beforeIngest(taken.records).catch(e =>\n          twinWarn(`[twin-fill] 중복 판정 기억을 못 채웠다 — ${String(e?.message ?? e)}. 넣기는 그대로 간다`)\n        )\n      }\n      const result = ingest(taken.records)\n      applied += result.applied\n      duplicates += result.duplicates ?? 0\n      rejectedCount += result.rejected?.length ?? 0\n      for (const r of result.rejected ?? []) {\n        /* 사유가 여럿이면 첫 줄로 묶는다 — 뒤는 대개 같은 원인의 곁가지다. */\n        const why = String((r as any)?.errors?.[0] ?? '(사유 없음)').slice(0, 120)\n        rejectedReasons[why] = (rejectedReasons[why] ?? 0) + 1\n      }\n      vocabulary += (result as any).vocabulary ?? 0\n      for (const [k, n] of Object.entries((result as any).undated ?? {})) undated[k] = (undated[k] ?? 0) + (n as number)\n    }\n\n    /*\n     * **번호가 나아가야 다음 쪽을 요청한다.** 원본이 빈 묶음에 물어본 번호를 그대로 돌려주는 계약이면,\n     * 나아감을 보지 않고 요청하면 무한히 돈다.\n     */\n    if (taken.advancedSeq === undefined || taken.advancedSeq <= since) {\n      if (taken.gap) return { applied, duplicates, rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}), vocabulary, ...(Object.keys(undated).length ? { undated } : {}), pages: pages + 1, ...seqPart(cursor, cursorKey), ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}), stopped: 'gap', detail: gapWord(taken.gap) }\n      return {\n        applied,\n        duplicates,\n        rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}),\n        vocabulary,\n        ...(Object.keys(undated).length ? { undated } : {}),\n        pages: pages + 1,\n        ...seqPart(cursor, cursorKey),\n        ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}),\n        stopped: 'no-progress',\n        detail: `번호가 ${since} 에서 나아가지 않았다 — 같은 것을 다시 받았다`\n      }\n    }\n\n    if (lowestSeq === undefined) lowestSeq = taken.lowestSeq\n    /* 밑에서부터 다시 받았으면 그 번호가 곧 우리가 가진 가장 낮은 번호다. */\n    cursor = withSeq(cursor, cursorKey, taken.advancedSeq, taken.firstSeq ?? lowestSeq)\n    await saveCursor(cursor as Record<string, unknown>).catch(err =>\n      twinWarn(`[twin-fill] 번호를 커서에 적지 못했다 (${cursorKey}=${taken.advancedSeq}) — ${err?.message ?? err}`)\n    )\n\n    /*\n     * **구멍이 있으면 멈춘다.** 원본의 아웃박스에 구멍이 있는 것이고, 이어 받으면 커서가 그 번호를\n     * 지나쳐 적혀 빠진 사실이 다시 오지 않는다.\n     */\n    if (taken.gap) {\n      return { applied, duplicates, rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}), vocabulary, ...(Object.keys(undated).length ? { undated } : {}), pages: pages + 1, ...seqPart(cursor, cursorKey), ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}), stopped: 'gap', detail: gapWord(taken.gap) }\n    }\n  }\n\n  /* 상한에 닿았다 — 조용히 끝내지 않는다. 사람이 다 받은 줄로 읽으면 안 된다. */\n  return {\n    applied,\n    duplicates,\n    rejected: rejectedCount, ...(Object.keys(rejectedReasons).length ? { rejectedReasons } : {}),\n    vocabulary,\n    ...(Object.keys(undated).length ? { undated } : {}),\n    pages,\n    ...seqPart(cursor, cursorKey),\n    ...(sourceRange ? { sourceRange } : {}), ...(lowestSeq !== undefined ? { lowestSeq } : {}),\n    stopped: 'page-limit',\n    detail: `${maxPages}쪽까지 받고 멈췄다 — 남은 것이 있을 수 있다. 다음 주기가 이어 받는다`\n  }\n}\n\nfunction seqPart(cursor: unknown, key: string): { lastSeq?: number } {\n  const seq = seqOf(cursor, key)\n  return seq === undefined ? {} : { lastSeq: seq }\n}\n\nfunction gapWord(gap: { expectedSeq: number; lastSeq: number }): string {\n  return `번호가 비었다 — ${gap.lastSeq} 다음이 ${gap.expectedSeq} 이어야 한다. 원본의 아웃박스에 구멍이 있다`\n}\n"]}

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

@@ -1,3 +1,4 @@
+export { rejectedForCaller, type RejectedForCaller } from './hook-rejected.js';
 import { type HookOutcome } from './hook-contract.js';
 /**
  * 훅 하나를 처리한다 — 찾고 · 확인하고 · 커넥터에게 옮기게 하고 · 유입으로 넘긴다.
@@ -11,10 +12,67 @@ export declare function handleHook(args: {
     instanceId: string;
     headers: Record<string, unknown>;
     body: unknown;
-    /** 레코드를 트윈에 넣는다 — 받은 수와 버린 수를 돌려준다. */
-    ingest: (instanceId: string, records: unknown[]) => {
-        applied: number;
-        duplicates: number;
-        rejected: number;
-    };
+    /**
+     * 받은 바이트 그대로 — 서명을 확인하려면 이것이 있어야 한다.
+     *
+     * 파싱한 객체를 다시 문자열로 만들면 키 순서와 공백이 달라져 서명이 맞지 않는다. 없으면 서명을 쓰는
+     * 요청은 거절된다(§`authorizeHook`).
+     */
+    rawBody?: string;
+    /** 서명 창을 재는 기준 시각. 부르는 쪽이 준다 — 여기서 읽으면 시험이 시계에 매인다. */
+    nowMs?: number;
+    /** 레코드를 트윈에 넣는다 — 받은 수와 **떨어진 것들**을 돌려준다. */
+    ingest: (instanceId: string, records: unknown[]) => IngestResult;
+    /**
+     * 구멍을 봤다 — **부르는 쪽이 무엇을 할지 정한다.**
+     *
+     * 여기서 backfill 을 직접 부르지 않는다. 이 파일은 `ingest`·`store` 를 인자로 받아 가볍게 유지한다
+     * (그래야 테스트가 엔진 없이 이 판정을 확인할 수 있다). backfill 을 import 하면 그 규율이 깨진다.
+     *
+     * 기다리지 않는 것도 부르는 쪽의 몫이다 — 훅의 응답이 늦으면 보내는 쪽이 되풀이한다.
+     */
+    onGap?: (scope: string) => void;
+    /**
+     * 저장소를 대신 쓰는 자리 — **시험이 재기동을 넣을 수 있게.**
+     *
+     * `ingest` 를 부르는 쪽이 넘겨 주는 것과 같은 이유다(위 §). 커서는 재기동을 넘어 살아야 하는데, 한
+     * 프로세스 안에서만 확인하면 「적히나」는 보이지만 「다시 세우면 읽히나」는 안 보인다. 그 둘이 갈린
+     * 결함을 이 저장소가 이미 겪었다.
+     */
+    store: HookStore;
 }): Promise<HookOutcome>;
+/**
+ * 유입이 돌려주는 것.
+ *
+ * 떨어진 것을 **수가 아니라 목록으로** 받는다. 수만 받으면 보내는 쪽에 「몇 건이 떨어졌다」밖에 말할 수
+ * 없고, 그러면 무엇을 따로 두어야 할지 알 수 없어 배치 전체를 다시 보내거나 전부 버린다.
+ */
+export interface IngestResult {
+    applied: number;
+    duplicates: number;
+    rejected: {
+        record: unknown;
+        errors: string[];
+    }[];
+    /**
+     * How many records were vocabulary rather than events — **needed so the reply's sum closes.**
+     *
+     * `liveIngest` has counted this all along and this boundary dropped it, because the callback was
+     * typed as `IngestResult` and vocabulary was not on it. So `offered` counted those records and
+     * none of the other three did, and a sender checking the sum would have seen a loss on ordinary
+     * traffic (§`WebhookResponse.offered`).
+     *
+     * Optional because an ingest that handles no vocabulary need not say zero, and a caller that
+     * simply does not know must not be made to claim none.
+     */
+    vocabulary?: number;
+}
+/**
+ * 훅이 저장소에 닿는 두 자리 — 연결을 찾는 것과 커서를 적는 것.
+ *
+ * 이 둘만 밖으로 낸다. 나머지는 인자만 보고 답하므로 시험이 데이터베이스를 세우지 않아도 된다.
+ */
+export interface HookStore {
+    load(domainId: string, source: string): Promise<any | null>;
+    saveCursor(refId: string, cursor: unknown): Promise<void>;
+}

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

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.rejectedForCaller = void 0;
 exports.handleHook = handleHook;
 /*
  * 연결된 시스템이 **밀어 주는** 사실을 받는 자리 — 웹훅.
@@ -45,9 +46,12 @@ exports.handleHook = handleHook;
  * 경계가 이미 거릅니다(§`FactDeduper`) — 이 파일이 따로 하지 않습니다. 응답에 몇 건이 중복이었는지
  * 함께 알립니다.
  */
-const shell_1 = require("@things-factory/shell");
-const twin_reference_js_1 = require("./twin-reference.js");
+const ops_contract_1 = require("@operato/ops-contract");
+const log_js_1 = require("../../engine/log.js");
 const reference_adapter_js_1 = require("./reference-adapter.js");
+const hook_rejected_js_1 = require("./hook-rejected.js");
+var hook_rejected_js_2 = require("./hook-rejected.js");
+Object.defineProperty(exports, "rejectedForCaller", { enumerable: true, get: function () { return hook_rejected_js_2.rejectedForCaller; } });
 const hook_contract_js_1 = require("./hook-contract.js");
 /**
  * 훅 하나를 처리한다 — 찾고 · 확인하고 · 커넥터에게 옮기게 하고 · 유입으로 넘긴다.
@@ -56,78 +60,312 @@ const hook_contract_js_1 = require("./hook-contract.js");
  * 그러면 규약을 확인하는 시험을 쓸 수 없다.
  */
 async function handleHook(args) {
-    const { domainId, source, instanceId, headers, body, ingest } = args;
-    const ref = await (0, shell_1.getRepository)(twin_reference_js_1.TwinReference)
-        .findOne({ where: { domain: { id: domainId }, source } })
-        .catch(() => null);
+    const { domainId, source, instanceId, headers, body, rawBody, ingest, onGap } = args;
+    const nowMs = args.nowMs ?? Date.now();
+    const { store } = args;
+    const ref = await store.load(domainId, source);
     if (!ref) {
-        return { status: hook_contract_js_1.HOOK_STATUS.unknownTarget, body: { ok: false, error: `unknown connection "${source}"` } };
+        return { status: ops_contract_1.WEBHOOK_STATUS.unknownTarget, body: { ok: false, error: `unknown connection "${source}"` } };
     }
     const cfg = ref.connectionConfig ?? {};
     const expected = String(cfg.hookSecret ?? '').trim();
     if (!expected) {
         /* 비밀값을 선언하지 않은 연결은 훅을 받지 않는다 — 기본이 거부다. */
         return {
-            status: hook_contract_js_1.HOOK_STATUS.badSecret,
+            status: ops_contract_1.WEBHOOK_STATUS.badSecret,
             body: {
                 ok: false,
                 error: `connection "${source}" declares no hookSecret — set one in the connection settings before pushing to it`
             }
         };
     }
-    if (!(0, hook_contract_js_1.secretMatches)((0, hook_contract_js_1.secretFromHeaders)(headers), expected)) {
-        return { status: hook_contract_js_1.HOOK_STATUS.badSecret, body: { ok: false, error: 'hook secret does not match' } };
+    const auth = (0, hook_contract_js_1.authorizeHook)({ headers, rawBody, secret: expected, nowMs });
+    if (auth.ok === false) {
+        return { status: ops_contract_1.WEBHOOK_STATUS.badSecret, body: { ok: false, error: auth.reason } };
     }
     const site = (0, hook_contract_js_1.producedInstance)(ref, instanceId);
     if (!site) {
         return {
-            status: hook_contract_js_1.HOOK_STATUS.unknownTarget,
+            status: ops_contract_1.WEBHOOK_STATUS.unknownTarget,
             body: { ok: false, error: `twin "${instanceId}" was not created by connection "${source}"` }
         };
     }
     const adapter = (0, reference_adapter_js_1.getAdapter)(String(ref.adapterType ?? ''));
     if (typeof adapter?.handleInbound !== 'function') {
         return {
-            status: hook_contract_js_1.HOOK_STATUS.unsupported,
+            status: ops_contract_1.WEBHOOK_STATUS.unsupported,
             body: { ok: false, error: `connector "${ref.adapterType}" cannot take pushed events (no handleInbound)` }
         };
     }
-    let records;
+    let batch;
     try {
-        records = adapter.handleInbound(cfg, site, body, headers) ?? [];
+        batch = adapter.handleInbound(cfg, site, body, headers);
     }
     catch (e) {
         /* 옮기지 못한 것은 그쪽 모양이 바뀐 것이다 — 다시 보내도 같으므로 재시도를 부르지 않는다. */
-        return { status: hook_contract_js_1.HOOK_STATUS.badPayload, body: { ok: false, error: e?.message ?? 'cannot translate the payload' } };
+        return { status: ops_contract_1.WEBHOOK_STATUS.badPayload, body: { ok: false, error: e?.message ?? 'cannot translate the payload' } };
     }
-    if (!Array.isArray(records)) {
-        return { status: hook_contract_js_1.HOOK_STATUS.badPayload, body: { ok: false, error: 'the connector did not return a list of records' } };
+    const items = batch?.items;
+    if (!Array.isArray(items)) {
+        return {
+            status: ops_contract_1.WEBHOOK_STATUS.badPayload,
+            body: { ok: false, error: 'the connector did not return a list of items' }
+        };
+    }
+    /*
+     * **번호 확인** — 이 자리가 프레임워크인 이유는 밀어 주는 모든 연결에 같은 규율이라야 하기 때문이다.
+     * 커넥터마다 만들면 한 곳이 빠지고, 빠진 그 연결에서만 사실이 없어진다.
+     *
+     * 판정은 `takeInSequence` 하나가 한다 — **backfill 하는 길도 같은 함수를 지난다.** 여기서 따로 만들면
+     * 두 길이 다른 규칙으로 받고, 한쪽만 고쳐지는 날이 온다.
+     */
+    const scope = typeof batch.scope === 'string' && batch.scope.trim() ? batch.scope.trim() : undefined;
+    /* 열쇠에 트윈을 넣는다 — 연결 하나가 트윈 여럿을 만들고 커서는 연결마다 한 행이다. */
+    const key = scope ? (0, hook_contract_js_1.pushCursorKey)(instanceId, scope) : undefined;
+    const taken = (0, hook_contract_js_1.takeInSequence)({
+        items,
+        scope,
+        lastSeq: key ? (0, hook_contract_js_1.seqOf)(ref.liveCursor, key) : undefined
+    });
+    if (taken.refused) {
+        /* 반쯤 확인한 것을 확인했다고 말하지 않는다. */
+        return { status: ops_contract_1.WEBHOOK_STATUS.badPayload, body: { ok: false, error: taken.refused } };
+    }
+    const numbered = taken.numbered;
+    const gap = taken.gap;
+    /*
+     * 첫 봉투가 1번이 아니면 **그 사실을 남긴다.** 커서가 없는 연결에 21번이 오면 커서가 21 로 뛰고,
+     * 그 앞 스무 건은 구멍으로도 안 세어진다. 실제로 plant 에서 그렇게 스무 건이 조용히 사라졌다.
+     *
+     * 손실이라고 말하지 않는다 — 늦게 붙은 트윈은 그 앞을 안 받기로 한 것이다. 수만 말하고 판단은
+     * 사람이 한다.
+     */
+    if (taken.firstUnseenBefore) {
+        (0, log_js_1.twinWarn)(`[twin-ingest] "${instanceId}" 의 ${scope ?? '(단위 없음)'} 를 ${taken.advancedSeq} 번부터 받기 시작했습니다 — ` +
+            `그 앞 ${taken.firstUnseenBefore}건은 받은 적이 없습니다. 원본이 오래 돌고 있었으면 정상이고, ` +
+            `보냈는데 못 받은 것이면 그만큼이 빠진 것입니다`);
     }
+    const advanced = taken.advancedSeq !== undefined && key ? { scope: key, seq: taken.advancedSeq } : undefined;
+    const records = taken.records;
     if (!records.length) {
-        /* 옮길 것이 없는 것은 오류가 아니다 — 그쪽이 우리와 무관한 것을 보낸 것일 수 있다. */
-        return { status: hook_contract_js_1.HOOK_STATUS.ok, body: { ok: true, offered: 0, applied: 0, duplicates: 0, rejected: 0 } };
+        /*
+         * 옮길 것이 없는 것은 오류가 아니다 — 그쪽이 우리와 무관한 것을 보낸 것일 수 있다. 다만 첫 봉투부터
+         * 구멍이면 그것은 받은 것이 없는 것이고, 그 앞부터 달라고 해야 한다.
+         */
+        if (gap) {
+            if (scope)
+                onGap?.(scope);
+            return gapOutcome(scope, gap);
+        }
+        if (advanced)
+            await saveSeq(store, ref, advanced.scope, advanced.seq, taken.firstSeq);
+        return {
+            status: ops_contract_1.WEBHOOK_STATUS.ok,
+            body: {
+                ok: true,
+                offered: 0,
+                applied: 0,
+                duplicates: 0,
+                vocabulary: 0,
+                rejected: [],
+                ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)
+            }
+        };
     }
     let result;
     try {
         result = ingest(instanceId, records);
     }
     catch (e) {
-        return { status: hook_contract_js_1.HOOK_STATUS.failed, body: { ok: false, error: e?.message ?? 'ingest failed' } };
+        return { status: ops_contract_1.WEBHOOK_STATUS.failed, body: { ok: false, error: e?.message ?? 'ingest failed' } };
     }
-    if (result.applied === 0 && result.duplicates === 0 && records.length > 0 && result.rejected === 0) {
+    const rejected = result.rejected ?? [];
+    /*
+     * ── 떨어진 것에 **봉투 id** 를 붙인다 (2026-09-07 측정) ──────────────────────
+     * 이 응답이 `{ record, errors }` 목록이었고, plant 은 그것을 **봉투 id 문자열 목록**으로 읽고
+     * 있었다. `Array.isArray` 는 통과하므로 그쪽 guard 도 안 걸렸다 — id 를 맞추는데 객체라 하나도
+     * 안 맞고 **묶음 전체가 「보냈음」으로 찍혔다.**
+     *
+     * 422 와 `ok: false` 를 보냈는데 그쪽 행은 재시도 0 · 오류 없음 · 보냈음이었다. 우리가 말했는데
+     * 상대가 못 알아듣는 모양이면, 말한 것이 아니다.
+     *
+     * 그래서 봉투 id 를 함께 싣는다. 보내는 쪽이 자기 행을 표시할 수 있고 까닭도 남는다.
+     *
+     * **id 를 못 찾으면 레코드를 그대로 싣는다.** 그때는 무엇이 떨어졌는지 알 방법이 그것뿐이고,
+     * 빈 id 를 실으면 보내는 쪽이 아무 행도 못 찾으면서 「알았다」고 여긴다.
+     *
+     * 짝은 **객체 동일성**으로 짓는다. `records` 는 `items` 의 순서와 원소를 그대로 들고 있고
+     * (§`takeInSequence`), 그래서 커넥터를 고치지 않고도 봉투로 되짚을 수 있다. 값으로 비교하면
+     * 같은 모양의 레코드 둘이 서로의 id 를 가져간다.
+     */
+    const forCaller = (0, hook_rejected_js_1.rejectedForCaller)(rejected, items);
+    if (result.applied === 0 && result.duplicates === 0 && rejected.length === 0 && !result.vocabulary) {
         /*
          * 넣었는데 한 건도 반영되지 않았고 중복도 거부도 아니면, 그 트윈이 실시간으로 돌지 않는 것이다.
-         * 200 을 주면 그쪽은 전달된 줄 알고 그 사실을 버린다. 그래서 재시도로 풀리지 않는다는 것을 코드로
-         * 말한다 — 사람이 트윈을 띄워야 한다.
+         * 200 을 주면 그쪽은 전달된 줄 알고 그 사실을 버린다.
+         *
+         * **커서를 올리지 않는다.** 한 건도 안 들어갔는데 번호를 올리면 그 번호는 다시 오지 않고, 트윈이
+         * 뜬 뒤에 그 구간이 비어 있게 된다.
+         *
+         * ── Vocabulary is why this test needs a fourth term (2026-09-07) ──────────
+         * This inference reads an absence as a cause, and one absence is legitimate: a batch that was
+         * entirely vocabulary applies no events, has no duplicates and rejects nothing, and yet
+         * everything in it landed (§`applyMasterData`). Without the last term the receiver answers
+         * 503 to correct traffic, and the sender then holds those facts and retries every thirty
+         * seconds for as long as they keep arriving — the reply invents a reason ("not running live")
+         * that the numbers do not support.
+         *
+         * Found by a test written for the response sum, not by reading this line.
+         *
+         * ── Why this branch has to say something out loud ─────────────────────────
+         * Measured today: a 503 from here leaves **no trace on either side.** The sender maps it to
+         * backpressure and returns without touching `attempts` or `lastError`, and this branch logged
+         * nothing, so a sender re-offering the same batch every thirty seconds is invisible to both.
+         *
+         * That is also why "it has not happened" could not be established: `attempts 0` on the seven
+         * vocabulary envelopes was offered as evidence and is not evidence, because this path never
+         * increments that counter. Telling a sender to come back forever is worth one line.
+         */
+        (0, log_js_1.twinWarn)(`[twin-hook] "${instanceId}" 에 ${records.length}건이 왔는데 한 건도 앉지 않아 ` +
+            `${NOT_LIVE_RETRY_MS / 1000}초 뒤 다시 오라고 답했습니다 — 트윈이 실시간으로 돌지 않는 것으로 봅니다. ` +
+            `보내는 쪽은 이 답에 재시도 횟수를 남기지 않으므로, 되풀이되면 이 줄만 늘어납니다`);
+        return {
+            status: ops_contract_1.WEBHOOK_STATUS.notLive,
+            body: {
+                ok: false,
+                error: `twin "${instanceId}" is not running live — nothing was applied`,
+                offered: records.length,
+                retryAfterMs: NOT_LIVE_RETRY_MS
+            }
+        };
+    }
+    if (advanced)
+        await saveSeq(store, ref, advanced.scope, advanced.seq, taken.firstSeq);
+    /*
+     * **구멍이 있으면 그것이 답을 정한다.** 앞의 것은 이미 들어갔으므로 `lastSeq` 까지는 보냄으로 표시하게
+     * 하고, 떨어진 것이 있으면 그것도 함께 싣는다 — 두 소식이 한 응답에 들어가야 보내는 쪽이 둘 다 한다.
+     */
+    if (gap) {
+        if (scope)
+            onGap?.(scope);
+        return gapOutcome(scope, gap, forCaller, advanced);
+    }
+    if (rejected.length) {
+        /*
+         * **다시 보내라고 하지 않는다.** 떨어진 것은 모양이 틀린 것이라 같은 것을 다시 보내도 또 떨어지고,
+         * 함께 간 나머지는 이미 들어갔으므로 두 번 들어간다.
          */
         return {
-            status: hook_contract_js_1.HOOK_STATUS.notLive,
-            body: { ok: false, error: `twin "${instanceId}" is not running live — nothing was applied`, offered: records.length }
+            status: ops_contract_1.WEBHOOK_STATUS.partial,
+            body: {
+                ok: false,
+                error: `${rejected.length} of ${records.length} records did not pass validation`,
+                offered: records.length,
+                applied: result.applied,
+                duplicates: result.duplicates,
+                vocabulary: result.vocabulary ?? 0,
+                rejected: forCaller,
+                ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)
+            }
         };
     }
     return {
-        status: hook_contract_js_1.HOOK_STATUS.ok,
-        body: { ok: true, offered: records.length, applied: result.applied, duplicates: result.duplicates, rejected: result.rejected }
+        status: ops_contract_1.WEBHOOK_STATUS.ok,
+        body: {
+            ok: true,
+            offered: records.length,
+            applied: result.applied,
+            duplicates: result.duplicates,
+            /*
+             * Always reported, even as zero — the sender's sum has a term for it either way, and a field
+             * that appears only sometimes makes an absent one indistinguishable from a receiver that
+             * does not count vocabulary at all.
+             */
+            vocabulary: result.vocabulary ?? 0,
+            rejected: [],
+            ...seqBody(scope, advanced, numbered, taken.firstUnseenBefore)
+        }
+    };
+}
+/**
+ * 구멍을 알리는 응답 — **앞의 것은 받았다는 것을 함께 말한다.**
+ *
+ * `lastSeq` 를 빼면 보내는 쪽은 이미 들어간 것까지 다시 보내고, 그것이 매번 중복으로 걸러지면서
+ * 처리량만 먹는다.
+ */
+/*
+ * 구멍을 본 자리에서 **바로 받는다** — 번호가 비었다는 것을 아는 가장 이른 순간이다.
+ *
+ * 기다리지 않는다. 훅의 응답이 이것 때문에 늦으면 보내는 쪽이 되풀이하고, 그러면 같은 봉투가 두 번
+ * 온다. 그리고 같은 단위를 1분 안에 두 번 부르지 않는다(§`FILL_DEBOUNCE_MS`) — 밀어 받는 쪽이
+ * 구멍 뒤의 봉투를 계속 보내면 그때마다 구멍 판정이 나기 때문이다.
+ */
+function gapOutcome(scope, gap, 
+/*
+ * 떨어진 것 — 봉투 id 를 알면 그것을, 모르면 레코드를 싣는다(§`InboundItem.eventId`).
+ * 보내는 쪽이 자기 행을 찾을 수 있어야 하고, 못 찾으면 무엇이 떨어졌는지라도 보여야 한다.
+ */
+rejected = [], advanced) {
+    return {
+        status: ops_contract_1.WEBHOOK_STATUS.sequenceGap,
+        body: {
+            ok: false,
+            error: 'sequence gap',
+            scope,
+            expectedSeq: gap.expectedSeq,
+            lastSeq: advanced?.seq ?? gap.lastSeq,
+            ...(rejected.length ? { rejected } : {})
+        }
+    };
+}
+/**
+ * 트윈이 안 돌 때 얼마나 쉬라고 할 것인가.
+ *
+ * 사람이 트윈을 띄워야 풀리므로 초 단위로 다시 두드릴 이유가 없다. 그렇다고 길게 잡으면 트윈이 뜬 뒤
+ * 그만큼 늦게 이어진다.
+ */
+const NOT_LIVE_RETRY_MS = 30_000;
+/**
+ * 응답에 번호를 어떻게 적나 — **확인한 것과 확인하지 않은 것을 구별한다.**
+ *
+ * 번호를 매기지 않는 원본은 확인할 것이 없다. 그것을 응답에서 「이상 없다」와 같아 보이게 두면, 어느
+ * 연결이 연속성을 지키고 있는지 아무도 알 수 없다.
+ */
+/*
+ * The return type is the contract's, narrowed to the fields this function fills.
+ *
+ * It was `Record<string, unknown>`, and because the result is **spread** into the reply, an index
+ * signature slips past the excess-property check entirely — the four fields below were unverified
+ * even after `HookOutcome.body` was typed. Naming them here is what makes the check reach them.
+ */
+function seqBody(scope, advanced, numbered, firstUnseenBefore) {
+    if (!numbered)
+        return { sequenceChecked: false };
+    return {
+        sequenceChecked: true,
+        scope,
+        lastSeq: advanced?.seq,
+        /*
+         * 첫 봉투였고 그 앞을 못 봤으면 **그 수를 보내는 쪽에 돌려준다.** 안 돌려주면 그 사실이 아무 데도
+         * 안 남는다 — 구멍으로도 안 세어지고 backfill 대상도 아니다(backfill 은 커서부터 묻는다).
+         */
+        ...(firstUnseenBefore ? { firstUnseenBefore } : {})
     };
 }
+/**
+ * 커서에 번호를 적는다 — **반영한 뒤에만.**
+ *
+ * 넣기 전에 올리면, 넣다가 실패했을 때 그 번호는 다시 오지 않는다. 보내는 쪽은 200 을 못 받았으니 다시
+ * 보내겠지만, 그때는 커서가 이미 지나가 있어 `behind` 로 읽히고 버려진다.
+ *
+ * 적지 못하는 것은 사실 유입을 무르는 이유가 아니다 — 이미 들어간 사실은 그대로 두고, 다음 번호가 오면
+ * `gap` 으로 드러난다. 그래서 실패를 던지지 않고 남긴다.
+ */
+async function saveSeq(store, ref, scope, seq, firstSeq) {
+    const next = (0, hook_contract_js_1.withSeq)(ref.liveCursor, scope, seq, firstSeq);
+    ref.liveCursor = next;
+    await store
+        .saveCursor(ref.id, next)
+        .catch(err => (0, log_js_1.twinWarn)(`[twin-hook] 번호를 커서에 적지 못했다 (${scope}=${seq}) — ${err?.message ?? err}`));
+}
 //# sourceMappingURL=reference-hook.js.map