@things-factory/headless-twin 10.0.19 → 10.1.0

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

@@ -0,0 +1,187 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILL_PERIOD_MS = exports.FILL_DEBOUNCE_MS = void 0;
+exports.fillOnce = fillOnce;
+exports.requestFill = requestFill;
+exports.fillAllOnce = fillAllOnce;
+exports.startFillLoop = startFillLoop;
+exports.stopFillLoop = stopFillLoop;
+/*
+ * **빠진 구간을 언제 다시 받나** — 세 자리에서 부른다.
+ *
+ * ── 왜 세 자리인가 (인티그레이션 레인의 측정 권고, 2026-09-05) ──────────────
+ * ```
+ * 1  재기동 직후 한 번    우리가 내려가 있는 동안 그쪽이 보낸 것을 못 받았다
+ * 2  구멍을 본 그 자리     번호가 비었다는 것을 아는 순간이 가장 이르다
+ * 3  10분 그물            위 둘이 다 놓치는 경우 — 그쪽이 아예 안 보낸 구간
+ * ```
+ *
+ * **30초가 아니다.** 그 권고에 근거가 있었다 — backfill 은 원본에 조회를 걸고 저널을 읽는다.
+ * 30초마다 돌면 얻는 것 없이 두 쪽을 계속 친다. 놓친 구간은 10분 뒤에 받아도 사실이 달라지지 않는다.
+ *
+ * 규칙 주기(`rule-loop.ts`, 30초)에 얹지 않는 이유가 그것이다. 얹으면 간격이 그쪽에 묶이고, 나중에
+ * 규칙 주기를 바꾸면 이쪽이 소리 없이 따라간다.
+ *
+ * ── 겹쳐 돌지 않는다 ────────────────────────────────────────────────────────
+ * 한 바퀴가 간격보다 오래 걸리면 다음 발화가 겹친다. 겹치면 두 바퀴가 같은 구간을 받고, 그 순간
+ * 중복 판정이 두 벌의 기억을 갖는다.
+ *
+ * ── 도는 트윈만 본다 ────────────────────────────────────────────────────────
+ * 멈춘 트윈에는 사실을 넣을 커널이 없다. `runFill` 이 그것을 다시 확인하지만 여기서 미리 걸러
+ * 헛조회를 안 만든다.
+ */
+const log_js_1 = require("../../engine/log.js");
+const twin_engine_js_1 = require("../../engine/twin-engine.js");
+const reference_fill_run_js_1 = require("./reference-fill-run.js");
+/* 간격은 가벼운 파일에 있다 — 테스트가 붙게(§`fill-cadence.ts`). 부르는 쪽이 한 곳에서 가져가게 다시 내보낸다. */
+var fill_cadence_js_1 = require("./fill-cadence.js");
+Object.defineProperty(exports, "FILL_DEBOUNCE_MS", { enumerable: true, get: function () { return fill_cadence_js_1.FILL_DEBOUNCE_MS; } });
+Object.defineProperty(exports, "FILL_PERIOD_MS", { enumerable: true, get: function () { return fill_cadence_js_1.FILL_PERIOD_MS; } });
+const fill_cadence_js_2 = require("./fill-cadence.js");
+/** 어느 단위를 언제 마지막으로 받았나 — `domainId::instanceId::scope`. */
+const lastRun = new Map();
+let timer;
+let running = false;
+function recently(key, now) {
+    const last = lastRun.get(key);
+    return last !== undefined && now - last < fill_cadence_js_2.FILL_DEBOUNCE_MS;
+}
+/**
+ * 그 단위를 한 번 받는다 — **커서부터 이어서.**
+ *
+ * `from` 을 주지 않는다. 밑에서부터 다시 받는 것은 사람이 정하는 일이고(`fillTwinScope(from:)`),
+ * 주기가 스스로 할 일이 아니다 — 그것을 주기로 돌리면 매번 원본의 전 구간을 훑는다.
+ */
+async function fillOnce(domainId, instanceId, scope) {
+    const key = `${domainId}::${instanceId}::${scope}`;
+    const now = Date.now();
+    if (recently(key, now))
+        return undefined;
+    lastRun.set(key, now);
+    const out = await (0, reference_fill_run_js_1.runFill)({ domainId, instanceId, scope });
+    /*
+     * 받은 것이 있을 때만 말한다. 「받을 것이 없었다」를 10분마다 적으면 로그가 그 줄로 차고, 그러면
+     * 진짜 받은 날을 못 본다.
+     */
+    if (out.applied)
+        (0, log_js_1.twinLog)(`[twin-fill] "${instanceId}" · ${scope} — 빠진 구간에서 ${out.applied}건을 받았습니다`);
+    return out;
+}
+/**
+ * **구멍을 본 자리에서 부른다** — 기다리지 않는다.
+ *
+ * 훅의 응답이 이것 때문에 늦으면 보내는 쪽이 되풀이하고, 그러면 같은 봉투가 두 번 온다. 조치를
+ * 잇는 자리(`settleEffects`)와 같은 규율이다.
+ */
+function requestFill(domainId, instanceId, scope) {
+    void fillOnce(domainId, instanceId, scope).catch(err => (0, log_js_1.twinWarn)(`[twin-fill] "${instanceId}" · ${scope} 를 받지 못했습니다 — ${err?.message ?? err}`));
+}
+/**
+ * 도는 트윈을 한 바퀴 돈다.
+ *
+ * **어느 단위를 받을지는 커서가 말한다.** 커서에 적힌 흐름이 그동안 받아 온 것들이고, 그것이
+ * 없으면 아직 아무것도 안 받은 연결이라 받을 구간도 없다.
+ */
+async function fillAllOnce() {
+    let tried = 0;
+    let applied = 0;
+    for (const { domainId, instanceId } of twin_engine_js_1.TwinEngine.ownedTwins()) {
+        for (const scope of await scopesOf(domainId, instanceId)) {
+            tried++;
+            const out = await fillOnce(domainId, instanceId, scope);
+            applied += out?.applied ?? 0;
+        }
+    }
+    return { tried, applied };
+}
+/**
+ * 그 연결이 받아 온 단위들 — **커서에 적힌 것.**
+ *
+ * 커서 열쇠는 `instanceId::scope` 다(§`pushCursorKey`). 여기서 그 규칙을 다시 적지 않고 앞부분을
+ * 떼어 낸다 — 두 곳이 같은 규칙을 가지면 어긋나는 날 이 주기가 엉뚱한 단위를 받는다.
+ */
+async function scopesOf(domainId, instanceId) {
+    const { getRepository } = await Promise.resolve().then(() => __importStar(require('@things-factory/shell')));
+    const { TwinReference } = await Promise.resolve().then(() => __importStar(require('./twin-reference.js')));
+    const ref = await getRepository(TwinReference).findOne({ where: { domain: { id: domainId }, source: instanceId } });
+    const streams = ref?.liveCursor?.streams;
+    if (!streams || typeof streams !== 'object')
+        return [];
+    const prefix = `${instanceId}::`;
+    return Object.keys(streams)
+        .filter(k => k.startsWith(prefix))
+        .map(k => k.slice(prefix.length))
+        .filter(s => s);
+}
+/**
+ * 주기를 세운다 — 두 번 불러도 하나만 선다.
+ *
+ * **기동에서 한 번 먼저 돈다**(§1). 우리가 내려가 있는 동안 그쪽이 보낸 것을 그때 받는다. 첫 바퀴를
+ * 10분 뒤로 미루면 그 10분 동안 화면이 빈 구간을 그대로 보인다.
+ */
+function startFillLoop(periodMs = fill_cadence_js_2.FILL_PERIOD_MS) {
+    if (timer)
+        return;
+    const turn = () => {
+        if (running)
+            return;
+        running = true;
+        fillAllOnce()
+            .then(({ tried, applied }) => {
+            if (applied)
+                (0, log_js_1.twinLog)(`[twin-fill] 한 바퀴 — ${tried}개 단위에서 ${applied}건을 받았습니다`);
+        })
+            .catch(err => (0, log_js_1.twinError)(`[twin-fill] 주기가 실패했습니다 — ${err?.message ?? err}`))
+            .finally(() => {
+            running = false;
+        });
+    };
+    timer = setInterval(turn, periodMs);
+    /*
+     * 기동 직후 한 번. 조금 늦춰서 돈다 — 커널이 되살아나기 전에 부르면 도는 트윈이 0개라 아무것도
+     * 안 받고, 그러면 그 한 번이 없는 것과 같다.
+     */
+    setTimeout(turn, 15_000).unref?.();
+}
+/** 주기를 내린다 — 테스트가 재기동을 넣을 수 있게. */
+function stopFillLoop() {
+    if (timer)
+        clearInterval(timer);
+    timer = undefined;
+    running = false;
+    lastRun.clear();
+}
+//# sourceMappingURL=fill-loop.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fill-loop.js","sourceRoot":"","sources":["../../../server/service/reference/fill-loop.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * **빠진 구간을 언제 다시 받나** — 세 자리에서 부른다.\n *\n * ── 왜 세 자리인가 (인티그레이션 레인의 측정 권고, 2026-09-05) ──────────────\n * ```\n * 1  재기동 직후 한 번    우리가 내려가 있는 동안 그쪽이 보낸 것을 못 받았다\n * 2  구멍을 본 그 자리     번호가 비었다는 것을 아는 순간이 가장 이르다\n * 3  10분 그물            위 둘이 다 놓치는 경우 — 그쪽이 아예 안 보낸 구간\n * ```\n *\n * **30초가 아니다.** 그 권고에 근거가 있었다 — backfill 은 원본에 조회를 걸고 저널을 읽는다.\n * 30초마다 돌면 얻는 것 없이 두 쪽을 계속 친다. 놓친 구간은 10분 뒤에 받아도 사실이 달라지지 않는다.\n *\n * 규칙 주기(`rule-loop.ts`, 30초)에 얹지 않는 이유가 그것이다. 얹으면 간격이 그쪽에 묶이고, 나중에\n * 규칙 주기를 바꾸면 이쪽이 소리 없이 따라간다.\n *\n * ── 겹쳐 돌지 않는다 ────────────────────────────────────────────────────────\n * 한 바퀴가 간격보다 오래 걸리면 다음 발화가 겹친다. 겹치면 두 바퀴가 같은 구간을 받고, 그 순간\n * 중복 판정이 두 벌의 기억을 갖는다.\n *\n * ── 도는 트윈만 본다 ────────────────────────────────────────────────────────\n * 멈춘 트윈에는 사실을 넣을 커널이 없다. `runFill` 이 그것을 다시 확인하지만 여기서 미리 걸러\n * 헛조회를 안 만든다.\n */\nimport { twinError, twinLog, twinWarn } from '../../engine/log.js'\nimport { TwinEngine } from '../../engine/twin-engine.js'\n\nimport { runFill, type FillRunResult } from './reference-fill-run.js'\n\n/* 간격은 가벼운 파일에 있다 — 테스트가 붙게(§`fill-cadence.ts`). 부르는 쪽이 한 곳에서 가져가게 다시 내보낸다. */\nexport { FILL_DEBOUNCE_MS, FILL_PERIOD_MS } from './fill-cadence.js'\nimport { FILL_DEBOUNCE_MS, FILL_PERIOD_MS } from './fill-cadence.js'\n\n/** 어느 단위를 언제 마지막으로 받았나 — `domainId::instanceId::scope`. */\nconst lastRun = new Map<string, number>()\n\nlet timer: any\nlet running = false\n\nfunction recently(key: string, now: number): boolean {\n  const last = lastRun.get(key)\n  return last !== undefined && now - last < FILL_DEBOUNCE_MS\n}\n\n/**\n * 그 단위를 한 번 받는다 — **커서부터 이어서.**\n *\n * `from` 을 주지 않는다. 밑에서부터 다시 받는 것은 사람이 정하는 일이고(`fillTwinScope(from:)`),\n * 주기가 스스로 할 일이 아니다 — 그것을 주기로 돌리면 매번 원본의 전 구간을 훑는다.\n */\nexport async function fillOnce(domainId: string, instanceId: string, scope: string): Promise<FillRunResult | undefined> {\n  const key = `${domainId}::${instanceId}::${scope}`\n  const now = Date.now()\n  if (recently(key, now)) return undefined\n  lastRun.set(key, now)\n\n  const out = await runFill({ domainId, instanceId, scope })\n  /*\n   * 받은 것이 있을 때만 말한다. 「받을 것이 없었다」를 10분마다 적으면 로그가 그 줄로 차고, 그러면\n   * 진짜 받은 날을 못 본다.\n   */\n  if (out.applied) twinLog(`[twin-fill] \"${instanceId}\" · ${scope} — 빠진 구간에서 ${out.applied}건을 받았습니다`)\n  return out\n}\n\n/**\n * **구멍을 본 자리에서 부른다** — 기다리지 않는다.\n *\n * 훅의 응답이 이것 때문에 늦으면 보내는 쪽이 되풀이하고, 그러면 같은 봉투가 두 번 온다. 조치를\n * 잇는 자리(`settleEffects`)와 같은 규율이다.\n */\nexport function requestFill(domainId: string, instanceId: string, scope: string): void {\n  void fillOnce(domainId, instanceId, scope).catch(err =>\n    twinWarn(`[twin-fill] \"${instanceId}\" · ${scope} 를 받지 못했습니다 — ${err?.message ?? err}`)\n  )\n}\n\n/**\n * 도는 트윈을 한 바퀴 돈다.\n *\n * **어느 단위를 받을지는 커서가 말한다.** 커서에 적힌 흐름이 그동안 받아 온 것들이고, 그것이\n * 없으면 아직 아무것도 안 받은 연결이라 받을 구간도 없다.\n */\nexport async function fillAllOnce(): Promise<{ tried: number; applied: number }> {\n  let tried = 0\n  let applied = 0\n  for (const { domainId, instanceId } of TwinEngine.ownedTwins()) {\n    for (const scope of await scopesOf(domainId, instanceId)) {\n      tried++\n      const out = await fillOnce(domainId, instanceId, scope)\n      applied += out?.applied ?? 0\n    }\n  }\n  return { tried, applied }\n}\n\n/**\n * 그 연결이 받아 온 단위들 — **커서에 적힌 것.**\n *\n * 커서 열쇠는 `instanceId::scope` 다(§`pushCursorKey`). 여기서 그 규칙을 다시 적지 않고 앞부분을\n * 떼어 낸다 — 두 곳이 같은 규칙을 가지면 어긋나는 날 이 주기가 엉뚱한 단위를 받는다.\n */\nasync function scopesOf(domainId: string, instanceId: string): Promise<string[]> {\n  const { getRepository } = await import('@things-factory/shell')\n  const { TwinReference } = await import('./twin-reference.js')\n  const ref = await getRepository(TwinReference).findOne({ where: { domain: { id: domainId }, source: instanceId } })\n  const streams = (ref as any)?.liveCursor?.streams\n  if (!streams || typeof streams !== 'object') return []\n\n  const prefix = `${instanceId}::`\n  return Object.keys(streams)\n    .filter(k => k.startsWith(prefix))\n    .map(k => k.slice(prefix.length))\n    .filter(s => s)\n}\n\n/**\n * 주기를 세운다 — 두 번 불러도 하나만 선다.\n *\n * **기동에서 한 번 먼저 돈다**(§1). 우리가 내려가 있는 동안 그쪽이 보낸 것을 그때 받는다. 첫 바퀴를\n * 10분 뒤로 미루면 그 10분 동안 화면이 빈 구간을 그대로 보인다.\n */\nexport function startFillLoop(periodMs = FILL_PERIOD_MS): void {\n  if (timer) return\n\n  const turn = () => {\n    if (running) return\n    running = true\n    fillAllOnce()\n      .then(({ tried, applied }) => {\n        if (applied) twinLog(`[twin-fill] 한 바퀴 — ${tried}개 단위에서 ${applied}건을 받았습니다`)\n      })\n      .catch(err => twinError(`[twin-fill] 주기가 실패했습니다 — ${err?.message ?? err}`))\n      .finally(() => {\n        running = false\n      })\n  }\n\n  timer = setInterval(turn, periodMs)\n  /*\n   * 기동 직후 한 번. 조금 늦춰서 돈다 — 커널이 되살아나기 전에 부르면 도는 트윈이 0개라 아무것도\n   * 안 받고, 그러면 그 한 번이 없는 것과 같다.\n   */\n  setTimeout(turn, 15_000).unref?.()\n}\n\n/** 주기를 내린다 — 테스트가 재기동을 넣을 수 있게. */\nexport function stopFillLoop(): void {\n  if (timer) clearInterval(timer)\n  timer = undefined\n  running = false\n  lastRun.clear()\n}\n"]}

package/dist-server/service/reference/fill-span.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 이 레코드들이 덮는 시각 구간 — 하나도 시각을 말하지 않으면 `undefined`.
+ *
+ * **구간을 못 정하면 채우지 않는다.** 저널 전체를 읽는 쪽으로 넓히지 않는다 — 그것이 필요한
+ * 상황이면 조회가 아니라 unique index 로 풀어야 한다.
+ */
+export declare function spanOf(records: readonly unknown[]): {
+    from: Date;
+    to: Date;
+} | undefined;

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

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spanOf = spanOf;
+/*
+ * backfill 이 읽을 저널 구간을 정하는 판정.
+ *
+ * 조회 코드(`fill-dedupe.ts`)와 나눠 둔다 — 그쪽은 TypeORM entity 를 물어서 테스트 프로세스가
+ * 적재할 수 없다. 판정만 따로 두면 테스트가 가벼운 import 로 확인할 수 있다.
+ */
+const event_time_js_1 = require("../../engine/event-time.js");
+/**
+ * 이 레코드들이 덮는 시각 구간 — 하나도 시각을 말하지 않으면 `undefined`.
+ *
+ * **구간을 못 정하면 채우지 않는다.** 저널 전체를 읽는 쪽으로 넓히지 않는다 — 그것이 필요한
+ * 상황이면 조회가 아니라 unique index 로 풀어야 한다.
+ */
+function spanOf(records) {
+    let lo = Number.POSITIVE_INFINITY;
+    let hi = Number.NEGATIVE_INFINITY;
+    for (const r of records) {
+        const t = Date.parse(String((0, event_time_js_1.factEventTime)(r) ?? ''));
+        if (!Number.isFinite(t))
+            continue;
+        if (t < lo)
+            lo = t;
+        if (t > hi)
+            hi = t;
+    }
+    if (!Number.isFinite(lo))
+        return undefined;
+    /*
+     * 양쪽을 1초씩 넓힌다. 저장된 시각은 밀리초까지 있고 경계에서 같은 값이 부동소수로 갈릴 수 있다 —
+     * 넓게 읽는 것은 기억이 조금 더 차는 것뿐이라 손해가 없고, 좁게 읽으면 그 사실이 다시 앉는다.
+     */
+    return { from: new Date(lo - 1000), to: new Date(hi + 1000) };
+}
+//# sourceMappingURL=fill-span.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fill-span.js","sourceRoot":"","sources":["../../../server/service/reference/fill-span.ts"],"names":[],"mappings":";;AAcA,wBAeC;AA7BD;;;;;GAKG;AACH,8DAA0D;AAE1D;;;;;GAKG;AACH,SAAgB,MAAM,CAAC,OAA2B;IAChD,IAAI,EAAE,GAAG,MAAM,CAAC,iBAAiB,CAAA;IACjC,IAAI,EAAE,GAAG,MAAM,CAAC,iBAAiB,CAAA;IACjC,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAA,6BAAa,EAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAA;QACpD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,SAAQ;QACjC,IAAI,CAAC,GAAG,EAAE;YAAE,EAAE,GAAG,CAAC,CAAA;QAClB,IAAI,CAAC,GAAG,EAAE;YAAE,EAAE,GAAG,CAAC,CAAA;IACpB,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAAE,OAAO,SAAS,CAAA;IAC1C;;;OAGG;IACH,OAAO,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,CAAA;AAC/D,CAAC","sourcesContent":["/*\n * backfill 이 읽을 저널 구간을 정하는 판정.\n *\n * 조회 코드(`fill-dedupe.ts`)와 나눠 둔다 — 그쪽은 TypeORM entity 를 물어서 테스트 프로세스가\n * 적재할 수 없다. 판정만 따로 두면 테스트가 가벼운 import 로 확인할 수 있다.\n */\nimport { factEventTime } from '../../engine/event-time.js'\n\n/**\n * 이 레코드들이 덮는 시각 구간 — 하나도 시각을 말하지 않으면 `undefined`.\n *\n * **구간을 못 정하면 채우지 않는다.** 저널 전체를 읽는 쪽으로 넓히지 않는다 — 그것이 필요한\n * 상황이면 조회가 아니라 unique index 로 풀어야 한다.\n */\nexport function spanOf(records: readonly unknown[]): { from: Date; to: Date } | undefined {\n  let lo = Number.POSITIVE_INFINITY\n  let hi = Number.NEGATIVE_INFINITY\n  for (const r of records) {\n    const t = Date.parse(String(factEventTime(r) ?? ''))\n    if (!Number.isFinite(t)) continue\n    if (t < lo) lo = t\n    if (t > hi) hi = t\n  }\n  if (!Number.isFinite(lo)) return undefined\n  /*\n   * 양쪽을 1초씩 넓힌다. 저장된 시각은 밀리초까지 있고 경계에서 같은 값이 부동소수로 갈릴 수 있다 —\n   * 넓게 읽는 것은 기억이 조금 더 차는 것뿐이라 손해가 없고, 좁게 읽으면 그 사실이 다시 앉는다.\n   */\n  return { from: new Date(lo - 1000), to: new Date(hi + 1000) }\n}\n\n"]}

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

@@ -1,12 +1,13 @@
+import { type WebhookResponse } from '@operato/ops-contract';
 /** 훅 요청의 결과 — 상태 코드와 본문을 함께 정한다(부르는 쪽이 그대로 답한다). */
 export interface HookOutcome {
     status: number;
-    body: Record<string, unknown>;
+    body: WebhookResponse;
 }
 /**
  * 응답 코드 규약 — **계약이 정하고 여기서는 그것을 쓴다**(2026-08-31).
  *
- * 예전에는 이 표가 여기 있었고 보내는 쪽(operato-mes)에 또 있었다. 그래서 같은 409 를 양쪽이 다른
+ * 예전에는 이 표가 여기 있었고 보내는 쪽(operato-plant)에 또 있었다. 그래서 같은 409 를 양쪽이 다른
  * 뜻으로 썼다 — 여기서는 「그 트윈이 실시간으로 돌지 않는다」, 저쪽에서는 「번호가 비었다」였다.
  * 붙였다면 트윈이 안 도는 동안 보내는 쪽이 같은 구간을 계속 다시 보냈다.
  *
@@ -29,7 +30,7 @@ export declare function secretMatches(given: string, expected: string): boolean;
  * 인증 — **서명이 왔으면 서명을 보고, 아니면 비밀값을 본다.**
  *
  * 두 방식을 두는 이유는 밀어 주는 쪽의 사정이 다르기 때문이다. 이미 붙어 있는 커넥터는 비밀값을 헤더에
- * 싣는 방식으로 만들어졌고, 새로 만드는 것(operato-mes)은 서명을 쓴다. 서명 쪽이 낫다 — 비밀값을 그대로
+ * 싣는 방식으로 만들어졌고, 새로 만드는 것(operato-plant)은 서명을 쓴다. 서명 쪽이 낫다 — 비밀값을 그대로
  * 싣는 방식은 그 요청을 그대로 다시 보내는 것을 막지 못한다.
  *
  * **서명이 왔는데 확인할 수 없으면 거절한다.** 받은 바이트를 들고 있지 않으면(`rawBody` 가 없으면)
@@ -77,7 +78,90 @@ export declare function pushCursorKey(instanceId: string, scope: string): string
  */
 export declare function seqOf(cursor: unknown, scope: string): number | undefined;
 /** 그 단위의 번호만 바꾼 커서를 만든다 — 다른 흐름과 `since`·`seen` 은 그대로 둔다. */
-export declare function withSeq(cursor: unknown, scope: string, seq: number): Record<string, unknown>;
+export declare function withSeq(cursor: unknown, scope: string, seq: number, firstSeq?: number): Record<string, unknown>;
+/**
+ * 이 연결이 이 단위를 **몇 번부터 받기 시작했나** — 적힌 적이 없으면 `undefined`.
+ *
+ * 「앞이 비었나」를 답하려면 이 값이 있어야 한다. 없으면 **모른다고 말해야 한다** — 0 으로 답하면
+ * 1번부터 다 받은 것으로 읽힌다.
+ */
+export declare function firstSeqOf(cursor: unknown, scope: string): number | undefined;
+/**
+ * **번호대로 받을 수 있는 데까지 자른다** — 밀어 받는 길과 backfill 하는 길이 이 함수 하나를 지난다.
+ *
+ * ── 왜 갈라 두나 (2026-08-31) ────────────────────────────────────────────
+ * 이 판정이 훅 안에 박혀 있었다. backfill(`fetchSince`)이 같은 판정을 해야 하는데, 거기서 다시 만들면
+ * **두 길이 다른 규칙으로 받는다** — 한쪽만 고쳐지는 날이 오고, 어긋난 그 길에서만 사실이 사라진다.
+ *
+ * 번호 확인을 커넥터가 아니라 프레임워크로 가져온 것과 같은 이유다. 자리가 하나여야 한다.
+ *
+ * ── 첫 구멍에서 멈춘다 ───────────────────────────────────────────────────
+ * 구멍 뒤의 봉투를 받아들이면 그 구멍이 영영 메워지지 않는다. 보내는 쪽은 `expectedSeq` 부터 다시
+ * 보내고, 뒤엣것은 그때 함께 온다.
+ */
+export interface SequencedTake {
+    /** 받아들인 레코드 — 구멍 앞까지다. */
+    records: unknown[];
+    /** 번호를 확인했나. 번호를 매기지 않는 원본은 거짓이고, 그 사실을 응답에 남긴다. */
+    numbered: boolean;
+    /** 커서에 적을 번호 — 받은 것이 없으면 없다. */
+    advancedSeq?: number;
+    /** 구멍이 났다 — 그 앞부터 다시 받아야 한다. */
+    gap?: {
+        expectedSeq: number;
+        lastSeq: number;
+    };
+    /**
+     * 이 단위의 **첫 봉투였다** — 그 앞으로 몇 개를 못 봤나.
+     *
+     * ── 왜 이 칸이 생겼나 (2026-09-06 실측) ──────────────────────────────────
+     * plant 아웃박스의 1~20 이 400 으로 거절돼 그 연결에 커서가 없었다. 다음에 온 21번이 첫 봉투로
+     * 앉으며 **커서가 21 로 뛰었다.** 커서가 0 이었다면 같은 21이 구멍이었다.
+     *
+     * 스무 건이 없는데 구멍으로도 안 세어지고, 경고도 없고, backfill 대상도 아니었다 — backfill 은 커서부터
+     * 묻는다. 그 사실이 아무 데도 안 남았다.
+     *
+     * **손실이라고 말하지 않는다.** 원본이 오래 돌고 있는데 트윈을 나중에 붙이면 그 아래는 애초에
+     * 안 받기로 한 것이다. 계약은 둘을 구별할 수 없으므로 수만 낸다.
+     *
+     * 0 이면 1번부터 시작한 것이라 이 칸을 내지 않는다 — 말할 것이 없다.
+     */
+    firstUnseenBefore?: number;
+    /**
+     * 이 묶음의 첫 봉투가 **이 단위의 첫 봉투였다** — 그 번호.
+     *
+     * `firstUnseenBefore` 와 다르다: 이쪽은 1번부터 시작한 연결에도 있다(값 1). 커서에 적어 두면
+     * 나중에 「앞이 비었나」를 답할 수 있다.
+     */
+    firstSeq?: number;
+    /**
+     * 이 묶음에서 **가장 낮게 받아들인 번호** — 하나도 못 받았으면 없다.
+     *
+     * `firstSeq` 와 다르다. `firstSeq` 는 「이 단위의 첫 봉투였다」일 때만 있고, 이쪽은 언제나 있다.
+     *
+     * 밑에서부터 다시 받을 때 이것이 필요하다. `from: 0` 으로 부르면 커서가 0 이므로 seq 1 은
+     * `next` 판정이고 `firstSeq` 가 안 생긴다 — 그런데 우리는 실제로 1번부터 갖게 된다. 그 사실을
+     * 적어야 「앞이 비었나」에 답할 수 있다.
+     */
+    lowestSeq?: number;
+    /**
+     * 받을 수 없는 묶음 — 그 이유.
+     *
+     * 번호가 있는 봉투와 없는 봉투가 섞였거나 번호가 정수가 아니다. 둘 다 보내는 쪽의 결함이고,
+     * **반쯤 확인한 것을 확인했다고 말하지 않는다.**
+     */
+    refused?: string;
+}
+export declare function takeInSequence(args: {
+    items: {
+        record: unknown;
+        seq?: number;
+        at?: string;
+    }[];
+    scope?: string;
+    /** 이 단위에서 마지막으로 받아들인 번호. 받은 적이 없으면 `undefined`. */
+    lastSeq?: number;
+}): SequencedTake;
 /** 이 연결이 이 트윈을 만들었나 — 남의 트윈에 밀어 넣지 못하게. */
 export declare function producedInstance(ref: {
     scopeSpec?: any;

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

@@ -6,6 +6,8 @@ exports.authorizeHook = authorizeHook;
 exports.pushCursorKey = pushCursorKey;
 exports.seqOf = seqOf;
 exports.withSeq = withSeq;
+exports.firstSeqOf = firstSeqOf;
+exports.takeInSequence = takeInSequence;
 exports.producedInstance = producedInstance;
 /*
  * 웹훅의 규약 — 상태 코드 · 비밀값 · 어느 트윈인가.
@@ -51,11 +53,20 @@ exports.producedInstance = producedInstance;
  * 경계가 이미 거릅니다(§`FactDeduper`) — 이 파일이 따로 하지 않습니다. 응답에 몇 건이 중복이었는지
  * 함께 알립니다.
  */
+/*
+ * `WebhookResponse` comes from the root, not from `@operato/ops-contract/webhook`.
+ *
+ * That subpath resolves to `webhook-signature`, which is a separate module kept out of the barrel
+ * because it pulls in `node:crypto`. The module actually named `webhook.ts` — status codes, the
+ * envelope, the response — reaches consumers through the root barrel. Importing the response type
+ * from the subpath fails with TS2305, which is what happened here first.
+ */
+const ops_contract_1 = require("@operato/ops-contract");
 const webhook_1 = require("@operato/ops-contract/webhook");
 /**
  * 응답 코드 규약 — **계약이 정하고 여기서는 그것을 쓴다**(2026-08-31).
  *
- * 예전에는 이 표가 여기 있었고 보내는 쪽(operato-mes)에 또 있었다. 그래서 같은 409 를 양쪽이 다른
+ * 예전에는 이 표가 여기 있었고 보내는 쪽(operato-plant)에 또 있었다. 그래서 같은 409 를 양쪽이 다른
  * 뜻으로 썼다 — 여기서는 「그 트윈이 실시간으로 돌지 않는다」, 저쪽에서는 「번호가 비었다」였다.
  * 붙였다면 트윈이 안 도는 동안 보내는 쪽이 같은 구간을 계속 다시 보냈다.
  *
@@ -92,7 +103,7 @@ function secretMatches(given, expected) {
  * 인증 — **서명이 왔으면 서명을 보고, 아니면 비밀값을 본다.**
  *
  * 두 방식을 두는 이유는 밀어 주는 쪽의 사정이 다르기 때문이다. 이미 붙어 있는 커넥터는 비밀값을 헤더에
- * 싣는 방식으로 만들어졌고, 새로 만드는 것(operato-mes)은 서명을 쓴다. 서명 쪽이 낫다 — 비밀값을 그대로
+ * 싣는 방식으로 만들어졌고, 새로 만드는 것(operato-plant)은 서명을 쓴다. 서명 쪽이 낫다 — 비밀값을 그대로
  * 싣는 방식은 그 요청을 그대로 다시 보내는 것을 막지 못한다.
  *
  * **서명이 왔는데 확인할 수 없으면 거절한다.** 받은 바이트를 들고 있지 않으면(`rawBody` 가 없으면)
@@ -156,12 +167,102 @@ function seqOf(cursor, scope) {
     return typeof seq === 'number' && Number.isInteger(seq) ? seq : undefined;
 }
 /** 그 단위의 번호만 바꾼 커서를 만든다 — 다른 흐름과 `since`·`seen` 은 그대로 둔다. */
-function withSeq(cursor, scope, seq) {
+function withSeq(cursor, scope, seq, firstSeq) {
     const base = (cursor && typeof cursor === 'object' ? cursor : {});
     const streams = base.streams && typeof base.streams === 'object' ? { ...base.streams } : {};
-    streams[scope] = { ...(streams[scope] ?? {}), seq };
+    const prev = streams[scope] ?? {};
+    /*
+     * **`firstSeq` 는 한 번만 적힌다.** 이 연결이 이 단위를 몇 번부터 받기 시작했는지는 바뀌지 않는
+     * 사실이고, 나중에 덮으면 「앞이 비었나」를 다시 물을 수 없다.
+     *
+     * 그래서 첫 봉투 판정이 있을 때만 넘어온다(`SequencedTake.firstSeq`). 커서가 이미 나아간 뒤에
+     * 이 값을 만들면 그 번호는 첫 번호가 아니라 그때 마침 온 번호다.
+     */
+    streams[scope] = { ...prev, seq, ...(firstSeq !== undefined && prev.firstSeq === undefined ? { firstSeq } : {}) };
     return { ...base, streams };
 }
+/**
+ * 이 연결이 이 단위를 **몇 번부터 받기 시작했나** — 적힌 적이 없으면 `undefined`.
+ *
+ * 「앞이 비었나」를 답하려면 이 값이 있어야 한다. 없으면 **모른다고 말해야 한다** — 0 으로 답하면
+ * 1번부터 다 받은 것으로 읽힌다.
+ */
+function firstSeqOf(cursor, scope) {
+    const seq = cursor?.streams?.[scope]?.firstSeq;
+    return typeof seq === 'number' && Number.isInteger(seq) ? seq : undefined;
+}
+function takeInSequence(args) {
+    const { items, scope, lastSeq } = args;
+    const withSeq = items.filter(i => typeof i?.seq === 'number').length;
+    if (withSeq && withSeq !== items.length) {
+        return { records: [], numbered: false, refused: `mixed batch — ${withSeq} of ${items.length} items carry a sequence number` };
+    }
+    const numbered = withSeq > 0 && !!scope;
+    if (!numbered)
+        return { records: items.map(i => i.record), numbered: false };
+    let cursor = lastSeq;
+    let take = 0;
+    let gap;
+    /* 첫 봉투가 몇 번부터 시작했나 — 그 앞을 못 본 사실을 응답에 남긴다. */
+    let firstUnseenBefore;
+    /* 이 단위를 몇 번부터 받기 시작했나 — 커서에 적어 두면 「앞이 비었나」를 나중에 답할 수 있다. */
+    let firstSeq;
+    /* 이 묶음에서 가장 낮게 받아들인 번호 — 밑에서부터 다시 받을 때 이것이 firstSeq 가 된다. */
+    let lowestSeq;
+    for (const item of items) {
+        let verdict;
+        try {
+            verdict = (0, ops_contract_1.checkSequence)(cursor, item.seq);
+        }
+        catch (e) {
+            return { records: [], numbered: true, refused: e?.message ?? 'bad sequence number' };
+        }
+        if (verdict.kind === 'gap') {
+            gap = { expectedSeq: verdict.expectedSeq, lastSeq: verdict.lastSeq };
+            break;
+        }
+        if (verdict.kind === 'first') {
+            firstSeq = item.seq;
+            /*
+             * 계약이 `unseenBefore` 를 내면 그것을 쓴다. 설치된 판이 그보다 오래됐으면 번호에서 센다 —
+             * 첫 봉투의 번호 아래로 그만큼이 있고 우리는 그것을 받은 적이 없다.
+             *
+             * ⚠ 이 두 번째 길은 계약 0.9.9 가 깔리면 지운다. 그때까지 두는 이유는, 계약을 기다리며
+             * 비워 두면 **코드는 있는데 아무 일도 안 하는 상태**가 되고 그것이 이 결함의 원인과 같은
+             * 모양이기 때문이다.
+             */
+            const unseen = verdict.unseenBefore ?? item.seq - 1;
+            if (unseen > 0)
+                firstUnseenBefore = unseen;
+        }
+        if (lowestSeq === undefined)
+            lowestSeq = item.seq;
+        cursor = verdict.lastSeq;
+        take++;
+    }
+    return {
+        /*
+         * **봉투의 시각을 레코드에 얹는다** — 레코드가 자기 시각을 말하면 그것이 이긴다.
+         *
+         * 시각을 안 싣는 레코드는 ingest 시각으로 떨어지고, 그 값이 실행할 때마다 달라서 fact identity 가
+         * 매번 바뀐다. 그래서 같은 사실을 다시 받으면 dedupe 가 안 되고 새 사실로 앉는다 —
+         * `fillTwinScope` 를 두 번 돌렸더니 저널이 40 → 69건이 됐다(2026-09-06 측정).
+         */
+        records: items.slice(0, take).map(i => {
+            const r = i.record;
+            if (!i.at || r == null || typeof r !== 'object')
+                return i.record;
+            return r.at === undefined && r.eventTime === undefined ? { ...r, at: i.at } : i.record;
+        }),
+        numbered: true,
+        /* 앞의 것을 하나도 못 받았으면 커서를 올릴 것이 없다. */
+        ...(take > 0 && typeof cursor === 'number' ? { advancedSeq: cursor } : {}),
+        ...(gap ? { gap } : {}),
+        ...(firstUnseenBefore ? { firstUnseenBefore } : {}),
+        ...(firstSeq !== undefined ? { firstSeq } : {}),
+        ...(lowestSeq !== undefined ? { lowestSeq } : {})
+    };
+}
 /** 이 연결이 이 트윈을 만들었나 — 남의 트윈에 밀어 넣지 못하게. */
 function producedInstance(ref, instanceId) {
     const produced = ref?.scopeSpec?.produced ?? [];

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

@@ -1 +1 @@
-{"version":3,"file":"hook-contract.js","sourceRoot":"","sources":["../../../server/service/reference/hook-contract.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 웹훅의 규약 — 상태 코드 · 비밀값 · 어느 트윈인가.\n *\n * 데이터베이스를 부르는 부분과 갈라 둔다(§`reference-hook`): 규약만 있는 자리라야 시험이 엔티티를\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_HEADER, verifyWebhookSignature } from '@operato/ops-contract/webhook'\n\n/** 훅 요청의 결과 — 상태 코드와 본문을 함께 정한다(부르는 쪽이 그대로 답한다). */\nexport interface HookOutcome {\n  status: number\n  body: Record<string, unknown>\n}\n\n/**\n * 응답 코드 규약 — **계약이 정하고 여기서는 그것을 쓴다**(2026-08-31).\n *\n * 예전에는 이 표가 여기 있었고 보내는 쪽(operato-mes)에 또 있었다. 그래서 같은 409 를 양쪽이 다른\n * 뜻으로 썼다 — 여기서는 「그 트윈이 실시간으로 돌지 않는다」, 저쪽에서는 「번호가 비었다」였다.\n * 붙였다면 트윈이 안 도는 동안 보내는 쪽이 같은 구간을 계속 다시 보냈다.\n *\n * 판정표는 만드는 쪽과 읽는 쪽이 합의해야 하는 것이라 계약 층에 있다(`@operato/ops-contract`).\n * `notLive` 가 409 에서 503 으로 옮겨진 이유도 그 파일에 적혀 있다.\n *\n * **여기서 이름을 바꿔 다시 내보내지 않는다.** 부르는 쪽은 `WEBHOOK_STATUS` 를 계약에서 바로 가져온다.\n * 별명을 두면 같은 표에 이름이 둘이 되고, 다음 사람이 어느 쪽이 정본인지 물어야 한다.\n */\n\n/** 헤더에서 비밀값을 꺼낸다 — 두 가지 방식을 받는다(밀어 주는 쪽의 관습이 갈린다). */\nexport function secretFromHeaders(headers: Record<string, unknown> | undefined): string {\n  const pick = (k: string) => String((headers ?? {})[k] ?? '').trim()\n  const direct = pick('x-twin-hook-secret')\n  if (direct) return direct\n  const auth = pick('authorization')\n  return auth.toLowerCase().startsWith('bearer ') ? auth.slice(7).trim() : ''\n}\n\n/**\n * 비밀값 비교 — **길이가 다르면 바로 거절하고, 같으면 끝까지 비교한다.**\n *\n * 앞에서 다른 것을 발견하고 곧바로 답하면 응답 시간이 달라지고, 그 차이로 비밀값을 한 글자씩 알아낼 수\n * 있습니다. 그래서 같은 길이면 전부를 비교합니다.\n */\nexport function secretMatches(given: string, expected: string): boolean {\n  if (!expected || !given || given.length !== expected.length) return false\n  let diff = 0\n  for (let i = 0; i < expected.length; i++) diff |= given.charCodeAt(i) ^ expected.charCodeAt(i)\n  return diff === 0\n}\n\n/**\n * 인증 — **서명이 왔으면 서명을 보고, 아니면 비밀값을 본다.**\n *\n * 두 방식을 두는 이유는 밀어 주는 쪽의 사정이 다르기 때문이다. 이미 붙어 있는 커넥터는 비밀값을 헤더에\n * 싣는 방식으로 만들어졌고, 새로 만드는 것(operato-mes)은 서명을 쓴다. 서명 쪽이 낫다 — 비밀값을 그대로\n * 싣는 방식은 그 요청을 그대로 다시 보내는 것을 막지 못한다.\n *\n * **서명이 왔는데 확인할 수 없으면 거절한다.** 받은 바이트를 들고 있지 않으면(`rawBody` 가 없으면)\n * 파싱한 객체를 다시 문자열로 만들어 확인하고 싶어지는데, 키 순서와 공백이 달라져 어차피 맞지 않는다.\n * 맞지 않는 것을 통과시키면 서명이 있으나 마나 한 것이 된다.\n */\nexport function authorizeHook(args: {\n  headers: Record<string, unknown> | undefined\n  /** 받은 바이트 그대로. 서명을 쓰지 않는 연결에서는 없어도 된다. */\n  rawBody: string | undefined\n  /** 연결 설정에 저장된 비밀값. 서명과 비밀값이 같은 값을 쓴다. */\n  secret: string\n  nowMs: number\n}): { ok: true; method: 'signature' | 'secret' } | { ok: false; reason: string } {\n  const { headers, rawBody, secret, nowMs } = args\n  const pick = (k: string) => String((headers ?? {})[k] ?? '').trim()\n  const signature = pick(WEBHOOK_HEADER.signature)\n\n  if (signature) {\n    if (rawBody === undefined) {\n      return { ok: false, reason: 'signed request but the raw body was not kept — cannot verify' }\n    }\n    const verdict = verifyWebhookSignature({\n      secret,\n      timestamp: pick(WEBHOOK_HEADER.timestamp),\n      signature,\n      body: rawBody,\n      nowMs\n    })\n    /* `=== false` 로 본다 — 이 저장소는 `strictNullChecks` 가 꺼져 있어 참·거짓만으로는 좁혀지지 않는다. */\n    if (verdict.ok === false) return { ok: false, reason: `signature ${verdict.reason}` }\n    return { ok: true, method: 'signature' }\n  }\n\n  return secretMatches(secretFromHeaders(headers), secret)\n    ? { ok: true, method: 'secret' }\n    : { ok: false, reason: 'hook secret does not match' }\n}\n\n/**\n * 커서에 적을 열쇠 — **트윈까지 넣는다.**\n *\n * ── 왜 (2026-08-31, MES 레인 질문에서 나옴) ───────────────────────────────\n * 커서는 **연결마다** 한 행(`TwinReference.liveCursor`)에 산다. 그런데 연결 하나가 트윈 여럿을\n * 만든다(`scopeSpec.produced` 가 목록이다). 보내는 쪽의 단위 이름만으로 열쇠를 잡으면, 같은 연결의\n * 두 공장이 같은 이름(`EVENTS`)을 쓸 때 **한 계수기를 함께 쓴다.**\n *\n * 그러면 A 공장이 5까지 올린 뒤 B 공장이 1을 보내면 이미 본 번호가 되어 버려지고, A 가 6을 보내면\n * B 의 번호와 어긋나 끊임없이 「빠졌다」가 된다. 같은 부류가 이 저장소에서 이미 났다 — 두 공장의\n * 같은 번호가 한 자리에 겹쳤다.\n *\n * 보내는 쪽에 트윈 이름을 넣으라고 하지 않는다. 어디로 갈지는 주소가 이미 말했고, 그것을 본문에도\n * 적으라고 하면 둘이 어긋나는 날 어느 쪽을 믿을지 정해야 한다.\n */\nexport function pushCursorKey(instanceId: string, scope: string): string {\n  return `${instanceId}::${scope}`\n}\n\n/**\n * 커서에서 그 단위의 마지막 번호를 꺼낸다.\n *\n * 커서 모양은 `{ streams: { [흐름]: { since?, seen[], seq? } } }` 이고 **흐름 이름은 어댑터가 정한다**\n * (§`TwinReference.liveCursor`). 밀어 주는 연결에서는 그 이름이 곧 번호를 매기는 단위다.\n *\n * 자리를 따로 만들지 않는 이유는 「재기동을 넘어 사는 진행 위치」가 두 벌이 되기 때문이다. 폴링이 쓰는\n * `since` 와 밀어 주기가 쓰는 `seq` 는 둘 다 「이 흐름을 어디까지 읽었나」이고 원본이 되풀어 줄 수 있다.\n */\nexport function seqOf(cursor: unknown, scope: string): number | undefined {\n  const streams = (cursor as any)?.streams\n  const seq = streams?.[scope]?.seq\n  return typeof seq === 'number' && Number.isInteger(seq) ? seq : undefined\n}\n\n/** 그 단위의 번호만 바꾼 커서를 만든다 — 다른 흐름과 `since`·`seen` 은 그대로 둔다. */\nexport function withSeq(cursor: unknown, scope: string, seq: number): Record<string, unknown> {\n  const base = (cursor && typeof cursor === 'object' ? (cursor as Record<string, unknown>) : {}) as Record<string, any>\n  const streams = base.streams && typeof base.streams === 'object' ? { ...base.streams } : {}\n  streams[scope] = { ...(streams[scope] ?? {}), seq }\n  return { ...base, streams }\n}\n\n/** 이 연결이 이 트윈을 만들었나 — 남의 트윈에 밀어 넣지 못하게. */\nexport function producedInstance(ref: { scopeSpec?: any } | null | undefined, instanceId: string): { siteId: string } | undefined {\n  const produced: any[] = (ref?.scopeSpec as any)?.produced ?? []\n  const hit = produced.find(p => String(p?.instanceId ?? '') === instanceId)\n  return hit?.siteId ? { siteId: String(hit.siteId) } : undefined\n}\n\n"]}
+{"version":3,"file":"hook-contract.js","sourceRoot":"","sources":["../../../server/service/reference/hook-contract.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 웹훅의 규약 — 상태 코드 · 비밀값 · 어느 트윈인가.\n *\n * 데이터베이스를 부르는 부분과 갈라 둔다(§`reference-hook`): 규약만 있는 자리라야 시험이 엔티티를\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 */\n/*\n * `WebhookResponse` comes from the root, not from `@operato/ops-contract/webhook`.\n *\n * That subpath resolves to `webhook-signature`, which is a separate module kept out of the barrel\n * because it pulls in `node:crypto`. The module actually named `webhook.ts` — status codes, the\n * envelope, the response — reaches consumers through the root barrel. Importing the response type\n * from the subpath fails with TS2305, which is what happened here first.\n */\nimport { checkSequence, type WebhookResponse } from '@operato/ops-contract'\nimport { WEBHOOK_HEADER, verifyWebhookSignature } from '@operato/ops-contract/webhook'\n\n/*\n * The body is typed by the contract, not by this file (2026-09-07).\n *\n * It was `Record<string, unknown>`, which accepts anything — so nothing checked that what we reply\n * with is what a sender was told to expect. It was not: the contract declared `rejected` in prose\n * only, operato-plant guessed \"a list of envelope ids\", and a whole batch was stamped delivered\n * while one envelope never landed (mes_outbox_events seq 178 — SENT, attempts 0, no error).\n *\n * With `WebhookResponse` here, adding a field to a reply without declaring it fails the build on\n * this side, which is the side that would otherwise ship the surprise.\n */\n/** 훅 요청의 결과 — 상태 코드와 본문을 함께 정한다(부르는 쪽이 그대로 답한다). */\nexport interface HookOutcome {\n  status: number\n  body: WebhookResponse\n}\n\n/**\n * 응답 코드 규약 — **계약이 정하고 여기서는 그것을 쓴다**(2026-08-31).\n *\n * 예전에는 이 표가 여기 있었고 보내는 쪽(operato-plant)에 또 있었다. 그래서 같은 409 를 양쪽이 다른\n * 뜻으로 썼다 — 여기서는 「그 트윈이 실시간으로 돌지 않는다」, 저쪽에서는 「번호가 비었다」였다.\n * 붙였다면 트윈이 안 도는 동안 보내는 쪽이 같은 구간을 계속 다시 보냈다.\n *\n * 판정표는 만드는 쪽과 읽는 쪽이 합의해야 하는 것이라 계약 층에 있다(`@operato/ops-contract`).\n * `notLive` 가 409 에서 503 으로 옮겨진 이유도 그 파일에 적혀 있다.\n *\n * **여기서 이름을 바꿔 다시 내보내지 않는다.** 부르는 쪽은 `WEBHOOK_STATUS` 를 계약에서 바로 가져온다.\n * 별명을 두면 같은 표에 이름이 둘이 되고, 다음 사람이 어느 쪽이 정본인지 물어야 한다.\n */\n\n/** 헤더에서 비밀값을 꺼낸다 — 두 가지 방식을 받는다(밀어 주는 쪽의 관습이 갈린다). */\nexport function secretFromHeaders(headers: Record<string, unknown> | undefined): string {\n  const pick = (k: string) => String((headers ?? {})[k] ?? '').trim()\n  const direct = pick('x-twin-hook-secret')\n  if (direct) return direct\n  const auth = pick('authorization')\n  return auth.toLowerCase().startsWith('bearer ') ? auth.slice(7).trim() : ''\n}\n\n/**\n * 비밀값 비교 — **길이가 다르면 바로 거절하고, 같으면 끝까지 비교한다.**\n *\n * 앞에서 다른 것을 발견하고 곧바로 답하면 응답 시간이 달라지고, 그 차이로 비밀값을 한 글자씩 알아낼 수\n * 있습니다. 그래서 같은 길이면 전부를 비교합니다.\n */\nexport function secretMatches(given: string, expected: string): boolean {\n  if (!expected || !given || given.length !== expected.length) return false\n  let diff = 0\n  for (let i = 0; i < expected.length; i++) diff |= given.charCodeAt(i) ^ expected.charCodeAt(i)\n  return diff === 0\n}\n\n/**\n * 인증 — **서명이 왔으면 서명을 보고, 아니면 비밀값을 본다.**\n *\n * 두 방식을 두는 이유는 밀어 주는 쪽의 사정이 다르기 때문이다. 이미 붙어 있는 커넥터는 비밀값을 헤더에\n * 싣는 방식으로 만들어졌고, 새로 만드는 것(operato-plant)은 서명을 쓴다. 서명 쪽이 낫다 — 비밀값을 그대로\n * 싣는 방식은 그 요청을 그대로 다시 보내는 것을 막지 못한다.\n *\n * **서명이 왔는데 확인할 수 없으면 거절한다.** 받은 바이트를 들고 있지 않으면(`rawBody` 가 없으면)\n * 파싱한 객체를 다시 문자열로 만들어 확인하고 싶어지는데, 키 순서와 공백이 달라져 어차피 맞지 않는다.\n * 맞지 않는 것을 통과시키면 서명이 있으나 마나 한 것이 된다.\n */\nexport function authorizeHook(args: {\n  headers: Record<string, unknown> | undefined\n  /** 받은 바이트 그대로. 서명을 쓰지 않는 연결에서는 없어도 된다. */\n  rawBody: string | undefined\n  /** 연결 설정에 저장된 비밀값. 서명과 비밀값이 같은 값을 쓴다. */\n  secret: string\n  nowMs: number\n}): { ok: true; method: 'signature' | 'secret' } | { ok: false; reason: string } {\n  const { headers, rawBody, secret, nowMs } = args\n  const pick = (k: string) => String((headers ?? {})[k] ?? '').trim()\n  const signature = pick(WEBHOOK_HEADER.signature)\n\n  if (signature) {\n    if (rawBody === undefined) {\n      return { ok: false, reason: 'signed request but the raw body was not kept — cannot verify' }\n    }\n    const verdict = verifyWebhookSignature({\n      secret,\n      timestamp: pick(WEBHOOK_HEADER.timestamp),\n      signature,\n      body: rawBody,\n      nowMs\n    })\n    /* `=== false` 로 본다 — 이 저장소는 `strictNullChecks` 가 꺼져 있어 참·거짓만으로는 좁혀지지 않는다. */\n    if (verdict.ok === false) return { ok: false, reason: `signature ${verdict.reason}` }\n    return { ok: true, method: 'signature' }\n  }\n\n  return secretMatches(secretFromHeaders(headers), secret)\n    ? { ok: true, method: 'secret' }\n    : { ok: false, reason: 'hook secret does not match' }\n}\n\n/**\n * 커서에 적을 열쇠 — **트윈까지 넣는다.**\n *\n * ── 왜 (2026-08-31, MES 레인 질문에서 나옴) ───────────────────────────────\n * 커서는 **연결마다** 한 행(`TwinReference.liveCursor`)에 산다. 그런데 연결 하나가 트윈 여럿을\n * 만든다(`scopeSpec.produced` 가 목록이다). 보내는 쪽의 단위 이름만으로 열쇠를 잡으면, 같은 연결의\n * 두 공장이 같은 이름(`EVENTS`)을 쓸 때 **한 계수기를 함께 쓴다.**\n *\n * 그러면 A 공장이 5까지 올린 뒤 B 공장이 1을 보내면 이미 본 번호가 되어 버려지고, A 가 6을 보내면\n * B 의 번호와 어긋나 끊임없이 「빠졌다」가 된다. 같은 부류가 이 저장소에서 이미 났다 — 두 공장의\n * 같은 번호가 한 자리에 겹쳤다.\n *\n * 보내는 쪽에 트윈 이름을 넣으라고 하지 않는다. 어디로 갈지는 주소가 이미 말했고, 그것을 본문에도\n * 적으라고 하면 둘이 어긋나는 날 어느 쪽을 믿을지 정해야 한다.\n */\nexport function pushCursorKey(instanceId: string, scope: string): string {\n  return `${instanceId}::${scope}`\n}\n\n/**\n * 커서에서 그 단위의 마지막 번호를 꺼낸다.\n *\n * 커서 모양은 `{ streams: { [흐름]: { since?, seen[], seq? } } }` 이고 **흐름 이름은 어댑터가 정한다**\n * (§`TwinReference.liveCursor`). 밀어 주는 연결에서는 그 이름이 곧 번호를 매기는 단위다.\n *\n * 자리를 따로 만들지 않는 이유는 「재기동을 넘어 사는 진행 위치」가 두 벌이 되기 때문이다. 폴링이 쓰는\n * `since` 와 밀어 주기가 쓰는 `seq` 는 둘 다 「이 흐름을 어디까지 읽었나」이고 원본이 되풀어 줄 수 있다.\n */\nexport function seqOf(cursor: unknown, scope: string): number | undefined {\n  const streams = (cursor as any)?.streams\n  const seq = streams?.[scope]?.seq\n  return typeof seq === 'number' && Number.isInteger(seq) ? seq : undefined\n}\n\n/** 그 단위의 번호만 바꾼 커서를 만든다 — 다른 흐름과 `since`·`seen` 은 그대로 둔다. */\nexport function withSeq(cursor: unknown, scope: string, seq: number, firstSeq?: number): Record<string, unknown> {\n  const base = (cursor && typeof cursor === 'object' ? (cursor as Record<string, unknown>) : {}) as Record<string, any>\n  const streams = base.streams && typeof base.streams === 'object' ? { ...base.streams } : {}\n  const prev = streams[scope] ?? {}\n  /*\n   * **`firstSeq` 는 한 번만 적힌다.** 이 연결이 이 단위를 몇 번부터 받기 시작했는지는 바뀌지 않는\n   * 사실이고, 나중에 덮으면 「앞이 비었나」를 다시 물을 수 없다.\n   *\n   * 그래서 첫 봉투 판정이 있을 때만 넘어온다(`SequencedTake.firstSeq`). 커서가 이미 나아간 뒤에\n   * 이 값을 만들면 그 번호는 첫 번호가 아니라 그때 마침 온 번호다.\n   */\n  streams[scope] = { ...prev, seq, ...(firstSeq !== undefined && prev.firstSeq === undefined ? { firstSeq } : {}) }\n  return { ...base, streams }\n}\n\n/**\n * 이 연결이 이 단위를 **몇 번부터 받기 시작했나** — 적힌 적이 없으면 `undefined`.\n *\n * 「앞이 비었나」를 답하려면 이 값이 있어야 한다. 없으면 **모른다고 말해야 한다** — 0 으로 답하면\n * 1번부터 다 받은 것으로 읽힌다.\n */\nexport function firstSeqOf(cursor: unknown, scope: string): number | undefined {\n  const seq = (cursor as any)?.streams?.[scope]?.firstSeq\n  return typeof seq === 'number' && Number.isInteger(seq) ? seq : undefined\n}\n\n/**\n * **번호대로 받을 수 있는 데까지 자른다** — 밀어 받는 길과 backfill 하는 길이 이 함수 하나를 지난다.\n *\n * ── 왜 갈라 두나 (2026-08-31) ────────────────────────────────────────────\n * 이 판정이 훅 안에 박혀 있었다. backfill(`fetchSince`)이 같은 판정을 해야 하는데, 거기서 다시 만들면\n * **두 길이 다른 규칙으로 받는다** — 한쪽만 고쳐지는 날이 오고, 어긋난 그 길에서만 사실이 사라진다.\n *\n * 번호 확인을 커넥터가 아니라 프레임워크로 가져온 것과 같은 이유다. 자리가 하나여야 한다.\n *\n * ── 첫 구멍에서 멈춘다 ───────────────────────────────────────────────────\n * 구멍 뒤의 봉투를 받아들이면 그 구멍이 영영 메워지지 않는다. 보내는 쪽은 `expectedSeq` 부터 다시\n * 보내고, 뒤엣것은 그때 함께 온다.\n */\nexport interface SequencedTake {\n  /** 받아들인 레코드 — 구멍 앞까지다. */\n  records: unknown[]\n  /** 번호를 확인했나. 번호를 매기지 않는 원본은 거짓이고, 그 사실을 응답에 남긴다. */\n  numbered: boolean\n  /** 커서에 적을 번호 — 받은 것이 없으면 없다. */\n  advancedSeq?: number\n  /** 구멍이 났다 — 그 앞부터 다시 받아야 한다. */\n  gap?: { expectedSeq: number; lastSeq: number }\n  /**\n   * 이 단위의 **첫 봉투였다** — 그 앞으로 몇 개를 못 봤나.\n   *\n   * ── 왜 이 칸이 생겼나 (2026-09-06 실측) ──────────────────────────────────\n   * plant 아웃박스의 1~20 이 400 으로 거절돼 그 연결에 커서가 없었다. 다음에 온 21번이 첫 봉투로\n   * 앉으며 **커서가 21 로 뛰었다.** 커서가 0 이었다면 같은 21이 구멍이었다.\n   *\n   * 스무 건이 없는데 구멍으로도 안 세어지고, 경고도 없고, backfill 대상도 아니었다 — backfill 은 커서부터\n   * 묻는다. 그 사실이 아무 데도 안 남았다.\n   *\n   * **손실이라고 말하지 않는다.** 원본이 오래 돌고 있는데 트윈을 나중에 붙이면 그 아래는 애초에\n   * 안 받기로 한 것이다. 계약은 둘을 구별할 수 없으므로 수만 낸다.\n   *\n   * 0 이면 1번부터 시작한 것이라 이 칸을 내지 않는다 — 말할 것이 없다.\n   */\n  firstUnseenBefore?: number\n  /**\n   * 이 묶음의 첫 봉투가 **이 단위의 첫 봉투였다** — 그 번호.\n   *\n   * `firstUnseenBefore` 와 다르다: 이쪽은 1번부터 시작한 연결에도 있다(값 1). 커서에 적어 두면\n   * 나중에 「앞이 비었나」를 답할 수 있다.\n   */\n  firstSeq?: number\n  /**\n   * 이 묶음에서 **가장 낮게 받아들인 번호** — 하나도 못 받았으면 없다.\n   *\n   * `firstSeq` 와 다르다. `firstSeq` 는 「이 단위의 첫 봉투였다」일 때만 있고, 이쪽은 언제나 있다.\n   *\n   * 밑에서부터 다시 받을 때 이것이 필요하다. `from: 0` 으로 부르면 커서가 0 이므로 seq 1 은\n   * `next` 판정이고 `firstSeq` 가 안 생긴다 — 그런데 우리는 실제로 1번부터 갖게 된다. 그 사실을\n   * 적어야 「앞이 비었나」에 답할 수 있다.\n   */\n  lowestSeq?: number\n  /**\n   * 받을 수 없는 묶음 — 그 이유.\n   *\n   * 번호가 있는 봉투와 없는 봉투가 섞였거나 번호가 정수가 아니다. 둘 다 보내는 쪽의 결함이고,\n   * **반쯤 확인한 것을 확인했다고 말하지 않는다.**\n   */\n  refused?: string\n}\n\nexport function takeInSequence(args: {\n  items: { record: unknown; seq?: number; at?: string }[]\n  scope?: string\n  /** 이 단위에서 마지막으로 받아들인 번호. 받은 적이 없으면 `undefined`. */\n  lastSeq?: number\n}): SequencedTake {\n  const { items, scope, lastSeq } = args\n\n  const withSeq = items.filter(i => typeof i?.seq === 'number').length\n  if (withSeq && withSeq !== items.length) {\n    return { records: [], numbered: false, refused: `mixed batch — ${withSeq} of ${items.length} items carry a sequence number` }\n  }\n  const numbered = withSeq > 0 && !!scope\n\n  if (!numbered) return { records: items.map(i => i.record), numbered: false }\n\n  let cursor = lastSeq\n  let take = 0\n  let gap: { expectedSeq: number; lastSeq: number } | undefined\n  /* 첫 봉투가 몇 번부터 시작했나 — 그 앞을 못 본 사실을 응답에 남긴다. */\n  let firstUnseenBefore: number | undefined\n  /* 이 단위를 몇 번부터 받기 시작했나 — 커서에 적어 두면 「앞이 비었나」를 나중에 답할 수 있다. */\n  let firstSeq: number | undefined\n  /* 이 묶음에서 가장 낮게 받아들인 번호 — 밑에서부터 다시 받을 때 이것이 firstSeq 가 된다. */\n  let lowestSeq: number | undefined\n  for (const item of items) {\n    let verdict\n    try {\n      verdict = checkSequence(cursor, item.seq as number)\n    } catch (e: any) {\n      return { records: [], numbered: true, refused: e?.message ?? 'bad sequence number' }\n    }\n    if (verdict.kind === 'gap') {\n      gap = { expectedSeq: verdict.expectedSeq, lastSeq: verdict.lastSeq }\n      break\n    }\n    if (verdict.kind === 'first') {\n      firstSeq = item.seq as number\n      /*\n       * 계약이 `unseenBefore` 를 내면 그것을 쓴다. 설치된 판이 그보다 오래됐으면 번호에서 센다 —\n       * 첫 봉투의 번호 아래로 그만큼이 있고 우리는 그것을 받은 적이 없다.\n       *\n       * ⚠ 이 두 번째 길은 계약 0.9.9 가 깔리면 지운다. 그때까지 두는 이유는, 계약을 기다리며\n       * 비워 두면 **코드는 있는데 아무 일도 안 하는 상태**가 되고 그것이 이 결함의 원인과 같은\n       * 모양이기 때문이다.\n       */\n      const unseen = (verdict as any).unseenBefore ?? (item.seq as number) - 1\n      if (unseen > 0) firstUnseenBefore = unseen\n    }\n    if (lowestSeq === undefined) lowestSeq = item.seq as number\n    cursor = verdict.lastSeq\n    take++\n  }\n\n  return {\n    /*\n     * **봉투의 시각을 레코드에 얹는다** — 레코드가 자기 시각을 말하면 그것이 이긴다.\n     *\n     * 시각을 안 싣는 레코드는 ingest 시각으로 떨어지고, 그 값이 실행할 때마다 달라서 fact identity 가\n     * 매번 바뀐다. 그래서 같은 사실을 다시 받으면 dedupe 가 안 되고 새 사실로 앉는다 —\n     * `fillTwinScope` 를 두 번 돌렸더니 저널이 40 → 69건이 됐다(2026-09-06 측정).\n     */\n    records: items.slice(0, take).map(i => {\n      const r = i.record as any\n      if (!i.at || r == null || typeof r !== 'object') return i.record\n      return r.at === undefined && r.eventTime === undefined ? { ...r, at: i.at } : i.record\n    }),\n    numbered: true,\n    /* 앞의 것을 하나도 못 받았으면 커서를 올릴 것이 없다. */\n    ...(take > 0 && typeof cursor === 'number' ? { advancedSeq: cursor } : {}),\n    ...(gap ? { gap } : {}),\n    ...(firstUnseenBefore ? { firstUnseenBefore } : {}),\n    ...(firstSeq !== undefined ? { firstSeq } : {}),\n    ...(lowestSeq !== undefined ? { lowestSeq } : {})\n  }\n}\n\n/** 이 연결이 이 트윈을 만들었나 — 남의 트윈에 밀어 넣지 못하게. */\nexport function producedInstance(ref: { scopeSpec?: any } | null | undefined, instanceId: string): { siteId: string } | undefined {\n  const produced: any[] = (ref?.scopeSpec as any)?.produced ?? []\n  const hit = produced.find(p => String(p?.instanceId ?? '') === instanceId)\n  return hit?.siteId ? { siteId: String(hit.siteId) } : undefined\n}\n\n"]}