@things-factory/webhook 10.1.29 → 10.1.31

package/dist-server/service/outbox/dispatcher.d.ts

@@ -0,0 +1,46 @@
+import { type DeliveryOutcome } from './delivery.js';
+import type { OutboxStore } from './store.js';
+/**
+ * One delivery: take what is pending on a stream, offer it to the peer, and do to our rows what the
+ * peer's answer says.
+ *
+ * Moved from operato-plant's `mes-outbox-dispatcher.ts` (ADR-0078 decision 2 ②). The judgement was already
+ * outside this function — `interpretResponse`, `settlement`, `rowEffectOf` — so what is left is the order
+ * of things. Three changes on the way, and no others:
+ *
+ *  - it reads and writes through an `OutboxStore` instead of an `EntityManager`;
+ *  - the headers a receiver wants beside the contract's (`X-Mes-Site` and the like) come in as `headers`.
+ *    They belong to the destination, not to the machine;
+ *  - being asked to wait is written down (`store.noteHeld`), and a batch that goes in clears it.
+ *
+ * `fetch` and `say` are arguments so that this function can be run by a test. It could not be before: it
+ * needed an EntityManager and a receiver answering 503, and the branch that matters most — backpressure —
+ * carried a comment saying no test reached it.
+ */
+export interface DispatchConfig {
+    endpoint: string;
+    secret: string;
+    /** Extra request headers this receiver asks for. The contract's own headers are added here. */
+    headers?: Record<string, string>;
+    /** The name clock readings are kept under — one per peer, so two peers' clocks are not mixed. */
+    clockKey: string;
+    batchSize?: number;
+}
+export interface DispatchReport {
+    outcome: DeliveryOutcome | {
+        kind: 'idle';
+    };
+    sent: number;
+    retryAfterMs?: number;
+}
+export interface Say {
+    info(what: string): void;
+    warn(what: string): void;
+    error(what: string): void;
+}
+export interface DispatchDeps {
+    fetch: typeof fetch;
+    say: Say;
+    now?: () => Date;
+}
+export declare function dispatchPending(store: OutboxStore, config: DispatchConfig, deps: DispatchDeps): Promise<DispatchReport>;

package/dist-server/service/outbox/dispatcher.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchPending = dispatchPending;
+const webhook_1 = require("@operato/ops-contract/webhook");
+const delivery_js_1 = require("./delivery.js");
+const settlement_js_1 = require("./settlement.js");
+const row_effect_js_1 = require("./row-effect.js");
+const clock_offset_js_1 = require("../observability/clock-offset.js");
+const trace_context_js_1 = require("../observability/trace-context.js");
+const DEFAULT_BATCH_SIZE = 200;
+async function dispatchPending(store, config, deps) {
+    const { say } = deps;
+    const now = deps.now ?? (() => new Date());
+    const take = config.batchSize ?? DEFAULT_BATCH_SIZE;
+    const pending = await store.pending(take);
+    if (!pending.length) {
+        return { outcome: { kind: 'idle' }, sent: 0 };
+    }
+    const ids = pending.map(row => row.id);
+    const body = JSON.stringify((0, delivery_js_1.buildBatch)(pending));
+    const timestamp = now().toISOString();
+    const trace = (0, trace_context_js_1.traceFor)(undefined);
+    let status;
+    let parsed;
+    try {
+        const response = await deps.fetch(config.endpoint, {
+            method: 'POST',
+            headers: {
+                ...(config.headers ?? {}),
+                'Content-Type': 'application/json',
+                [webhook_1.WEBHOOK_HEADER.timestamp]: timestamp,
+                [webhook_1.WEBHOOK_HEADER.signature]: (0, delivery_js_1.sign)(config.secret, timestamp, body),
+                [trace_context_js_1.TRACEPARENT]: (0, trace_context_js_1.toTraceparent)(trace)
+            },
+            body
+        });
+        status = response.status;
+        parsed = await response.json().catch(() => ({}));
+        (0, clock_offset_js_1.noteClockReading)(config.clockKey, (0, clock_offset_js_1.offsetFrom)(response.headers.get('date') ?? undefined, Date.now()));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        say.warn(`[webhook] outbox batch ${(0, trace_context_js_1.traceTag)(trace)} did not reach the receiver — ${reason}`);
+        await store.markAttempted(ids, reason);
+        return { outcome: { kind: 'retry', reason }, sent: 0 };
+    }
+    const outcome = (0, delivery_js_1.interpretResponse)(status, parsed);
+    switch (outcome.kind) {
+        case 'accepted':
+        case 'partial': {
+            const sent = await settle(store, pending, outcome.lastSeq, outcome.kind === 'partial' ? outcome.rejected : [], deps);
+            await store.noteTaken();
+            if (outcome.tally) {
+                const line = `[webhook] ${(0, delivery_js_1.describeTally)(outcome.tally)}`;
+                if (outcome.tally.balanced) {
+                    say.info(line);
+                }
+                else {
+                    say.warn(line);
+                }
+            }
+            else {
+                say.info('[webhook] the receiver did not send its counts — the offered total cannot be checked');
+            }
+            return { outcome, sent };
+        }
+        case 'gap': {
+            const sent = outcome.lastSeq === undefined ? 0 : await settle(store, pending, outcome.lastSeq, outcome.rejected, deps);
+            await store.rewindFrom(outcome.expectedSeq);
+            await store.noteTaken();
+            say.info(`[webhook] the receiver asked to resume from seq ${outcome.expectedSeq}`);
+            return { outcome, sent };
+        }
+        default: {
+            /* What an answer does to our rows is judged in one place. This switch does not judge again. */
+            const effect = (0, row_effect_js_1.rowEffectOf)(outcome, pending.length);
+            if (effect.rows === 'hold') {
+                await store.noteHeld(effect.retryAfterMs, now());
+                say[effect.say.level](effect.say.what);
+                return { outcome, sent: 0, retryAfterMs: effect.retryAfterMs };
+            }
+            if (effect.rows === 'fail') {
+                await store.markAttempted(ids, effect.reason);
+                await store.markFailed(ids);
+                say[effect.say.level](effect.say.what);
+                return { outcome, sent: 0 };
+            }
+            if (effect.rows === 'attempt') {
+                await store.markAttempted(ids, effect.reason);
+                if (effect.say) {
+                    say[effect.say.level](effect.say.what);
+                }
+            }
+            return { outcome, sent: 0 };
+        }
+    }
+}
+async function settle(store, pending, lastSeq, rejectedIds, deps) {
+    const { sentIds, failedIds } = (0, settlement_js_1.settlement)(pending, lastSeq, rejectedIds);
+    if (sentIds.length) {
+        await store.markSent(sentIds, (deps.now ?? (() => new Date()))());
+    }
+    if (failedIds.length) {
+        await store.markRejected(failedIds, 'rejected by the receiver during validation');
+        deps.say.warn(`[webhook] the receiver rejected ${failedIds.length} record(s) — see the payload log on its side`);
+    }
+    return sentIds.length;
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist-server/service/outbox/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../../server/service/outbox/dispatcher.ts"],"names":[],"mappings":";;AAwDA,0CAqGC;AA7JD,2DAA8D;AAE9D,+CAAwG;AACxG,mDAA4C;AAC5C,mDAA6C;AAE7C,sEAA+E;AAC/E,wEAAkG;AA+ClG,MAAM,kBAAkB,GAAG,GAAG,CAAA;AAEvB,KAAK,UAAU,eAAe,CAAC,KAAkB,EAAE,MAAsB,EAAE,IAAkB;IAClG,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;IACpB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAA;IAC1C,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,IAAI,kBAAkB,CAAA;IAEnD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QACpB,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,CAAA;IAC/C,CAAC;IAED,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAA,wBAAU,EAAC,OAAO,CAAC,CAAC,CAAA;IAChD,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC,WAAW,EAAE,CAAA;IACrC,MAAM,KAAK,GAAG,IAAA,2BAAQ,EAAC,SAAS,CAAC,CAAA;IAEjC,IAAI,MAAc,CAAA;IAClB,IAAI,MAAe,CAAA;IACnB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE;YACjD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;gBACzB,cAAc,EAAE,kBAAkB;gBAClC,CAAC,wBAAc,CAAC,SAAS,CAAC,EAAE,SAAS;gBACrC,CAAC,wBAAc,CAAC,SAAS,CAAC,EAAE,IAAA,kBAAI,EAAC,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC;gBAChE,CAAC,8BAAW,CAAC,EAAE,IAAA,gCAAa,EAAC,KAAK,CAAC;aACpC;YACD,IAAI;SACL,CAAC,CAAA;QACF,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAA;QACxB,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QAEhD,IAAA,kCAAgB,EAAC,MAAM,CAAC,QAAQ,EAAE,IAAA,4BAAU,EAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;IACtG,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACrE,GAAG,CAAC,IAAI,CAAC,0BAA0B,IAAA,2BAAQ,EAAC,KAAK,CAAC,iCAAiC,MAAM,EAAE,CAAC,CAAA;QAC5F,MAAM,KAAK,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;QACtC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,CAAA;IACxD,CAAC;IAED,MAAM,OAAO,GAAG,IAAA,+BAAiB,EAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEjD,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,UAAU,CAAC;QAChB,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;YACpH,MAAM,KAAK,CAAC,SAAS,EAAE,CAAA;YAEvB,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;gBAClB,MAAM,IAAI,GAAG,aAAa,IAAA,2BAAa,EAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAA;gBAExD,IAAI,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;oBAC3B,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBAChB,CAAC;qBAAM,CAAC;oBACN,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBAChB,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,IAAI,CAAC,sFAAsF,CAAC,CAAA;YAClG,CAAC;YAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;QAC1B,CAAC;QAED,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;YAEtH,MAAM,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;YAC3C,MAAM,KAAK,CAAC,SAAS,EAAE,CAAA;YACvB,GAAG,CAAC,IAAI,CAAC,mDAAmD,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;YAClF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;QAC1B,CAAC;QAED,OAAO,CAAC,CAAC,CAAC;YACR,+FAA+F;YAC/F,MAAM,MAAM,GAAG,IAAA,2BAAW,EAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;YAEnD,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBAC3B,MAAM,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,CAAA;gBAChD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;gBACtC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAA;YAChE,CAAC;YAED,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBAC3B,MAAM,KAAK,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;gBAC7C,MAAM,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAA;gBAC3B,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;gBACtC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,CAAA;YAC7B,CAAC;YAED,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC9B,MAAM,KAAK,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;gBAE7C,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC;oBACf,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;gBACxC,CAAC;YACH,CAAC;YAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,CAAA;QAC7B,CAAC;IACH,CAAC;AACH,CAAC;AAED,KAAK,UAAU,MAAM,CACnB,KAAkB,EAClB,OAAmC,EACnC,OAAe,EACf,WAA8B,EAC9B,IAAkB;IAElB,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,IAAA,0BAAU,EAAC,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,CAAA;IAExE,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAA;IACnE,CAAC;IAED,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;QACrB,MAAM,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,4CAA4C,CAAC,CAAA;QACjF,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,mCAAmC,SAAS,CAAC,MAAM,8CAA8C,CAAC,CAAA;IAClH,CAAC;IAED,OAAO,OAAO,CAAC,MAAM,CAAA;AACvB,CAAC","sourcesContent":["import { WEBHOOK_HEADER } from '@operato/ops-contract/webhook'\n\nimport { buildBatch, describeTally, interpretResponse, sign, type DeliveryOutcome } from './delivery.js'\nimport { settlement } from './settlement.js'\nimport { rowEffectOf } from './row-effect.js'\nimport type { OutboxStore, StoredOutboxRow } from './store.js'\nimport { noteClockReading, offsetFrom } from '../observability/clock-offset.js'\nimport { TRACEPARENT, toTraceparent, traceFor, traceTag } from '../observability/trace-context.js'\n\n/**\n * One delivery: take what is pending on a stream, offer it to the peer, and do to our rows what the\n * peer's answer says.\n *\n * Moved from operato-plant's `mes-outbox-dispatcher.ts` (ADR-0078 decision 2 ②). The judgement was already\n * outside this function — `interpretResponse`, `settlement`, `rowEffectOf` — so what is left is the order\n * of things. Three changes on the way, and no others:\n *\n *  - it reads and writes through an `OutboxStore` instead of an `EntityManager`;\n *  - the headers a receiver wants beside the contract's (`X-Mes-Site` and the like) come in as `headers`.\n *    They belong to the destination, not to the machine;\n *  - being asked to wait is written down (`store.noteHeld`), and a batch that goes in clears it.\n *\n * `fetch` and `say` are arguments so that this function can be run by a test. It could not be before: it\n * needed an EntityManager and a receiver answering 503, and the branch that matters most — backpressure —\n * carried a comment saying no test reached it.\n */\nexport interface DispatchConfig {\n  endpoint: string\n  secret: string\n  /** Extra request headers this receiver asks for. The contract's own headers are added here. */\n  headers?: Record<string, string>\n  /** The name clock readings are kept under — one per peer, so two peers' clocks are not mixed. */\n  clockKey: string\n  batchSize?: number\n}\n\nexport interface DispatchReport {\n  outcome: DeliveryOutcome | { kind: 'idle' }\n  sent: number\n  retryAfterMs?: number\n}\n\nexport interface Say {\n  info(what: string): void\n  warn(what: string): void\n  error(what: string): void\n}\n\nexport interface DispatchDeps {\n  fetch: typeof fetch\n  say: Say\n  now?: () => Date\n}\n\nconst DEFAULT_BATCH_SIZE = 200\n\nexport async function dispatchPending(store: OutboxStore, config: DispatchConfig, deps: DispatchDeps): Promise<DispatchReport> {\n  const { say } = deps\n  const now = deps.now ?? (() => new Date())\n  const take = config.batchSize ?? DEFAULT_BATCH_SIZE\n\n  const pending = await store.pending(take)\n\n  if (!pending.length) {\n    return { outcome: { kind: 'idle' }, sent: 0 }\n  }\n\n  const ids = pending.map(row => row.id)\n  const body = JSON.stringify(buildBatch(pending))\n  const timestamp = now().toISOString()\n  const trace = traceFor(undefined)\n\n  let status: number\n  let parsed: unknown\n  try {\n    const response = await deps.fetch(config.endpoint, {\n      method: 'POST',\n      headers: {\n        ...(config.headers ?? {}),\n        'Content-Type': 'application/json',\n        [WEBHOOK_HEADER.timestamp]: timestamp,\n        [WEBHOOK_HEADER.signature]: sign(config.secret, timestamp, body),\n        [TRACEPARENT]: toTraceparent(trace)\n      },\n      body\n    })\n    status = response.status\n    parsed = await response.json().catch(() => ({}))\n\n    noteClockReading(config.clockKey, offsetFrom(response.headers.get('date') ?? undefined, Date.now()))\n  } catch (error) {\n    const reason = error instanceof Error ? error.message : String(error)\n    say.warn(`[webhook] outbox batch ${traceTag(trace)} did not reach the receiver — ${reason}`)\n    await store.markAttempted(ids, reason)\n    return { outcome: { kind: 'retry', reason }, sent: 0 }\n  }\n\n  const outcome = interpretResponse(status, parsed)\n\n  switch (outcome.kind) {\n    case 'accepted':\n    case 'partial': {\n      const sent = await settle(store, pending, outcome.lastSeq, outcome.kind === 'partial' ? outcome.rejected : [], deps)\n      await store.noteTaken()\n\n      if (outcome.tally) {\n        const line = `[webhook] ${describeTally(outcome.tally)}`\n\n        if (outcome.tally.balanced) {\n          say.info(line)\n        } else {\n          say.warn(line)\n        }\n      } else {\n        say.info('[webhook] the receiver did not send its counts — the offered total cannot be checked')\n      }\n\n      return { outcome, sent }\n    }\n\n    case 'gap': {\n      const sent = outcome.lastSeq === undefined ? 0 : await settle(store, pending, outcome.lastSeq, outcome.rejected, deps)\n\n      await store.rewindFrom(outcome.expectedSeq)\n      await store.noteTaken()\n      say.info(`[webhook] the receiver asked to resume from seq ${outcome.expectedSeq}`)\n      return { outcome, sent }\n    }\n\n    default: {\n      /* What an answer does to our rows is judged in one place. This switch does not judge again. */\n      const effect = rowEffectOf(outcome, pending.length)\n\n      if (effect.rows === 'hold') {\n        await store.noteHeld(effect.retryAfterMs, now())\n        say[effect.say.level](effect.say.what)\n        return { outcome, sent: 0, retryAfterMs: effect.retryAfterMs }\n      }\n\n      if (effect.rows === 'fail') {\n        await store.markAttempted(ids, effect.reason)\n        await store.markFailed(ids)\n        say[effect.say.level](effect.say.what)\n        return { outcome, sent: 0 }\n      }\n\n      if (effect.rows === 'attempt') {\n        await store.markAttempted(ids, effect.reason)\n\n        if (effect.say) {\n          say[effect.say.level](effect.say.what)\n        }\n      }\n\n      return { outcome, sent: 0 }\n    }\n  }\n}\n\nasync function settle(\n  store: OutboxStore,\n  pending: readonly StoredOutboxRow[],\n  lastSeq: number,\n  rejectedIds: readonly string[],\n  deps: DispatchDeps\n): Promise<number> {\n  const { sentIds, failedIds } = settlement(pending, lastSeq, rejectedIds)\n\n  if (sentIds.length) {\n    await store.markSent(sentIds, (deps.now ?? (() => new Date()))())\n  }\n\n  if (failedIds.length) {\n    await store.markRejected(failedIds, 'rejected by the receiver during validation')\n    deps.say.warn(`[webhook] the receiver rejected ${failedIds.length} record(s) — see the payload log on its side`)\n  }\n\n  return sentIds.length\n}\n"]}

package/dist-server/service/outbox/page.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 목록을 자를 때 **잘렸다는 사실을 함께 낸다.**
+ *
+ * 「500건이 왔다」와 「500건이 전부다」를 구별할 수 없으면 받는 쪽은 언제 멈춰야 할지 모른다. 정확히
+ * 상한만큼 남은 경우가 실제로 온다.
+ *
+ * 방법은 **한 건 더 읽는 것**이다. 상한보다 많이 읽히면 더 있는 것이고, 그 한 건은 버린다. 세는 질의를
+ * 따로 하지 않으므로 큰 표에서도 비용이 같다.
+ */
+export interface Page<T> {
+    items: T[];
+    hasMore: boolean;
+}
+/**
+ * @param rows 상한보다 **한 건 더** 읽은 결과
+ * @param take 상한
+ */
+export declare function pageOf<T>(rows: T[], take: number): Page<T>;

package/dist-server/service/outbox/page.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pageOf = pageOf;
+/**
+ * @param rows 상한보다 **한 건 더** 읽은 결과
+ * @param take 상한
+ */
+function pageOf(rows, take) {
+    if (take <= 0) {
+        throw new Error(`pageOf: take must be positive, got ${take}`);
+    }
+    return rows.length > take ? { items: rows.slice(0, take), hasMore: true } : { items: rows, hasMore: false };
+}
+//# sourceMappingURL=page.js.map

package/dist-server/service/outbox/page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.js","sourceRoot":"","sources":["../../../server/service/outbox/page.ts"],"names":[],"mappings":";;AAkBA,wBAKC;AATD;;;GAGG;AACH,SAAgB,MAAM,CAAI,IAAS,EAAE,IAAY;IAC/C,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,sCAAsC,IAAI,EAAE,CAAC,CAAA;IAC/D,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;AAC7G,CAAC","sourcesContent":["/**\n * 목록을 자를 때 **잘렸다는 사실을 함께 낸다.**\n *\n * 「500건이 왔다」와 「500건이 전부다」를 구별할 수 없으면 받는 쪽은 언제 멈춰야 할지 모른다. 정확히\n * 상한만큼 남은 경우가 실제로 온다.\n *\n * 방법은 **한 건 더 읽는 것**이다. 상한보다 많이 읽히면 더 있는 것이고, 그 한 건은 버린다. 세는 질의를\n * 따로 하지 않으므로 큰 표에서도 비용이 같다.\n */\nexport interface Page<T> {\n  items: T[]\n  hasMore: boolean\n}\n\n/**\n * @param rows 상한보다 **한 건 더** 읽은 결과\n * @param take 상한\n */\nexport function pageOf<T>(rows: T[], take: number): Page<T> {\n  if (take <= 0) {\n    throw new Error(`pageOf: take must be positive, got ${take}`)\n  }\n  return rows.length > take ? { items: rows.slice(0, take), hasMore: true } : { items: rows, hasMore: false }\n}\n"]}

package/dist-server/service/outbox/pump-gate.d.ts

@@ -0,0 +1,74 @@
+/**
+ * **Can this installation send at all** — a pure judgement, no imports, no environment read here.
+ *
+ * ═════════════════════════════════════════════════════════════════════════
+ * ## What used to guard this door, and why it moved
+ *
+ * The pump used to stand only if a destination was named in the configuration file. Destinations then
+ * moved to a table an administrator edits, and the door stayed where it was: a site could name its
+ * destination on the screen and **the pump still would not stand**. Rows piled up with nobody sending
+ * them, and nothing failed, so nobody knew.
+ *
+ * ## So the key is what declares a sender
+ *
+ * Destinations live in a table now, and the pump reads that table every round - a boot-time reading
+ * would not see a destination added later. What is left is the signing key. An installation with no
+ * key cannot deliver one record even with a destination: unsigned, the receiver refuses it. So the
+ * key is the declaration that this installation sends.
+ *
+ * ## The names belong to the caller, the shape belongs here
+ *
+ * This module never reads `process.env`, and it has **no default names**: a product that forgets to
+ * name its variables would otherwise sign with somebody else's key and nothing would say so. What the
+ * module does own is how a domain becomes a variable suffix - if each product wrote that rule itself,
+ * the same domain would look for different variables depending on which product asked.
+ *
+ * ```
+ * <common>                     one key for the installation - a single-site install
+ * <common>__MIRATEK_GUNSAN     one key per domain - what a multi-tenant install should use
+ * ```
+ *
+ * A domain's name is not known at boot, so this counts by prefix. Which domain gave the key is
+ * settled on that domain's turn, and named there.
+ *
+ * ⚠ This door answers "can we sign", not "is there anything to send". An installation with a key and
+ * no destination row still stands the pump - and says, once per domain with facts waiting, that it
+ * has nowhere to send them. That is better than not standing and saying nothing.
+ * ═════════════════════════════════════════════════════════════════════════
+ */
+/**
+ * The two variable name stems a product declares. **Required** - see above on why there is no default.
+ *
+ * `domainPrefix` is the stem the per-domain names are built on; `domainSecretName` makes the whole
+ * name from it.
+ */
+export interface SecretNames {
+    common: string;
+    domainPrefix: string;
+}
+/**
+ * The variable a domain's own key lives in.
+ *
+ * Anything that is not a letter or a digit becomes `_`, because that is what an environment variable
+ * name may hold. Written once, here: a product that rounded this differently would look for
+ * `MIRATEK_GUNSAN` while another looked for `MIRATEK-GUNSAN`, for the same domain.
+ */
+export declare function domainSecretName(prefix: string, subdomain: string): string;
+/**
+ * Does this installation hold any key to sign with?
+ *
+ * The environment arrives as an argument. Reading the process here would put this judgement out of
+ * reach of a test, and this is the judgement that decides whether anything is delivered at all.
+ */
+export declare function outboxCanSign(env: Record<string, string | undefined>, names: SecretNames, declaredSecret?: string): boolean;
+/**
+ * This domain's key: its own first, then the installation's common one.
+ *
+ * **Absent is `undefined`, never an empty string.** An empty string signs, and a request signed with
+ * nothing cannot be told from a forgery. Falling back to the common key stops here; a caller with
+ * neither has to stop and name the domain it was working on.
+ *
+ * A multi-tenant installation should give per-domain keys and no common one. Then a domain nobody
+ * gave a key to is caught, rather than opening with somebody else's.
+ */
+export declare function outboxSecretFor(env: Record<string, string | undefined>, names: SecretNames, subdomain: string, declaredSecret?: string): string | undefined;

package/dist-server/service/outbox/pump-gate.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * **Can this installation send at all** — a pure judgement, no imports, no environment read here.
+ *
+ * ═════════════════════════════════════════════════════════════════════════
+ * ## What used to guard this door, and why it moved
+ *
+ * The pump used to stand only if a destination was named in the configuration file. Destinations then
+ * moved to a table an administrator edits, and the door stayed where it was: a site could name its
+ * destination on the screen and **the pump still would not stand**. Rows piled up with nobody sending
+ * them, and nothing failed, so nobody knew.
+ *
+ * ## So the key is what declares a sender
+ *
+ * Destinations live in a table now, and the pump reads that table every round - a boot-time reading
+ * would not see a destination added later. What is left is the signing key. An installation with no
+ * key cannot deliver one record even with a destination: unsigned, the receiver refuses it. So the
+ * key is the declaration that this installation sends.
+ *
+ * ## The names belong to the caller, the shape belongs here
+ *
+ * This module never reads `process.env`, and it has **no default names**: a product that forgets to
+ * name its variables would otherwise sign with somebody else's key and nothing would say so. What the
+ * module does own is how a domain becomes a variable suffix - if each product wrote that rule itself,
+ * the same domain would look for different variables depending on which product asked.
+ *
+ * ```
+ * <common>                     one key for the installation - a single-site install
+ * <common>__MIRATEK_GUNSAN     one key per domain - what a multi-tenant install should use
+ * ```
+ *
+ * A domain's name is not known at boot, so this counts by prefix. Which domain gave the key is
+ * settled on that domain's turn, and named there.
+ *
+ * ⚠ This door answers "can we sign", not "is there anything to send". An installation with a key and
+ * no destination row still stands the pump - and says, once per domain with facts waiting, that it
+ * has nowhere to send them. That is better than not standing and saying nothing.
+ * ═════════════════════════════════════════════════════════════════════════
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.domainSecretName = domainSecretName;
+exports.outboxCanSign = outboxCanSign;
+exports.outboxSecretFor = outboxSecretFor;
+/**
+ * The variable a domain's own key lives in.
+ *
+ * Anything that is not a letter or a digit becomes `_`, because that is what an environment variable
+ * name may hold. Written once, here: a product that rounded this differently would look for
+ * `MIRATEK_GUNSAN` while another looked for `MIRATEK-GUNSAN`, for the same domain.
+ */
+function domainSecretName(prefix, subdomain) {
+    return `${prefix}${subdomain.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`;
+}
+/** A value that is only whitespace is no value: signing with it produces a signature that stands. */
+function filled(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/**
+ * Does this installation hold any key to sign with?
+ *
+ * The environment arrives as an argument. Reading the process here would put this judgement out of
+ * reach of a test, and this is the judgement that decides whether anything is delivered at all.
+ */
+function outboxCanSign(env, names, declaredSecret) {
+    if (filled(env[names.common]) || filled(declaredSecret)) {
+        return true;
+    }
+    return Object.keys(env).some(name => name.startsWith(names.domainPrefix) && filled(env[name]));
+}
+/**
+ * This domain's key: its own first, then the installation's common one.
+ *
+ * **Absent is `undefined`, never an empty string.** An empty string signs, and a request signed with
+ * nothing cannot be told from a forgery. Falling back to the common key stops here; a caller with
+ * neither has to stop and name the domain it was working on.
+ *
+ * A multi-tenant installation should give per-domain keys and no common one. Then a domain nobody
+ * gave a key to is caught, rather than opening with somebody else's.
+ */
+function outboxSecretFor(env, names, subdomain, declaredSecret) {
+    const mine = env[domainSecretName(names.domainPrefix, subdomain)];
+    if (filled(mine)) {
+        return mine;
+    }
+    if (filled(env[names.common])) {
+        return env[names.common];
+    }
+    return filled(declaredSecret) ? declaredSecret : undefined;
+}
+//# sourceMappingURL=pump-gate.js.map

package/dist-server/service/outbox/pump-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pump-gate.js","sourceRoot":"","sources":["../../../server/service/outbox/pump-gate.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;;AAoBH,4CAEC;AAaD,sCAUC;AAYD,0CAiBC;AA7DD;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAAC,MAAc,EAAE,SAAiB;IAChE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,EAAE,CAAA;AAC1E,CAAC;AAED,qGAAqG;AACrG,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAA;AAC7D,CAAC;AAED;;;;;GAKG;AACH,SAAgB,aAAa,CAC3B,GAAuC,EACvC,KAAkB,EAClB,cAAuB;IAEvB,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;QACxD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AAChG,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,eAAe,CAC7B,GAAuC,EACvC,KAAkB,EAClB,SAAiB,EACjB,cAAuB;IAEvB,MAAM,IAAI,GAAG,GAAG,CAAC,gBAAgB,CAAC,KAAK,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC,CAAA;IAEjE,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACjB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;QAC9B,OAAO,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;IAC1B,CAAC;IAED,OAAO,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAA;AAC5D,CAAC","sourcesContent":["/**\n * **Can this installation send at all** — a pure judgement, no imports, no environment read here.\n *\n * ═════════════════════════════════════════════════════════════════════════\n * ## What used to guard this door, and why it moved\n *\n * The pump used to stand only if a destination was named in the configuration file. Destinations then\n * moved to a table an administrator edits, and the door stayed where it was: a site could name its\n * destination on the screen and **the pump still would not stand**. Rows piled up with nobody sending\n * them, and nothing failed, so nobody knew.\n *\n * ## So the key is what declares a sender\n *\n * Destinations live in a table now, and the pump reads that table every round - a boot-time reading\n * would not see a destination added later. What is left is the signing key. An installation with no\n * key cannot deliver one record even with a destination: unsigned, the receiver refuses it. So the\n * key is the declaration that this installation sends.\n *\n * ## The names belong to the caller, the shape belongs here\n *\n * This module never reads `process.env`, and it has **no default names**: a product that forgets to\n * name its variables would otherwise sign with somebody else's key and nothing would say so. What the\n * module does own is how a domain becomes a variable suffix - if each product wrote that rule itself,\n * the same domain would look for different variables depending on which product asked.\n *\n * ```\n * <common>                     one key for the installation - a single-site install\n * <common>__MIRATEK_GUNSAN     one key per domain - what a multi-tenant install should use\n * ```\n *\n * A domain's name is not known at boot, so this counts by prefix. Which domain gave the key is\n * settled on that domain's turn, and named there.\n *\n * ⚠ This door answers \"can we sign\", not \"is there anything to send\". An installation with a key and\n * no destination row still stands the pump - and says, once per domain with facts waiting, that it\n * has nowhere to send them. That is better than not standing and saying nothing.\n * ═════════════════════════════════════════════════════════════════════════\n */\n\n/**\n * The two variable name stems a product declares. **Required** - see above on why there is no default.\n *\n * `domainPrefix` is the stem the per-domain names are built on; `domainSecretName` makes the whole\n * name from it.\n */\nexport interface SecretNames {\n  common: string\n  domainPrefix: string\n}\n\n/**\n * The variable a domain's own key lives in.\n *\n * Anything that is not a letter or a digit becomes `_`, because that is what an environment variable\n * name may hold. Written once, here: a product that rounded this differently would look for\n * `MIRATEK_GUNSAN` while another looked for `MIRATEK-GUNSAN`, for the same domain.\n */\nexport function domainSecretName(prefix: string, subdomain: string): string {\n  return `${prefix}${subdomain.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`\n}\n\n/** A value that is only whitespace is no value: signing with it produces a signature that stands. */\nfunction filled(value: unknown): boolean {\n  return typeof value === 'string' && value.trim().length > 0\n}\n\n/**\n * Does this installation hold any key to sign with?\n *\n * The environment arrives as an argument. Reading the process here would put this judgement out of\n * reach of a test, and this is the judgement that decides whether anything is delivered at all.\n */\nexport function outboxCanSign(\n  env: Record<string, string | undefined>,\n  names: SecretNames,\n  declaredSecret?: string\n): boolean {\n  if (filled(env[names.common]) || filled(declaredSecret)) {\n    return true\n  }\n\n  return Object.keys(env).some(name => name.startsWith(names.domainPrefix) && filled(env[name]))\n}\n\n/**\n * This domain's key: its own first, then the installation's common one.\n *\n * **Absent is `undefined`, never an empty string.** An empty string signs, and a request signed with\n * nothing cannot be told from a forgery. Falling back to the common key stops here; a caller with\n * neither has to stop and name the domain it was working on.\n *\n * A multi-tenant installation should give per-domain keys and no common one. Then a domain nobody\n * gave a key to is caught, rather than opening with somebody else's.\n */\nexport function outboxSecretFor(\n  env: Record<string, string | undefined>,\n  names: SecretNames,\n  subdomain: string,\n  declaredSecret?: string\n): string | undefined {\n  const mine = env[domainSecretName(names.domainPrefix, subdomain)]\n\n  if (filled(mine)) {\n    return mine\n  }\n\n  if (filled(env[names.common])) {\n    return env[names.common]\n  }\n\n  return filled(declaredSecret) ? declaredSecret : undefined\n}\n"]}

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

@@ -0,0 +1,114 @@
+/**
+ * **보낸 수와 앉은 수를 맞춰 본다** — 순수 판단.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * ── 오늘 이것이 없어서 무슨 일이 났나 ──────────────────────────────────────
+ * 2026-09-05 하루에 세 번, 사실이 안 갔는데 **양쪽 다 초록**이었다.
+ *
+ * ```
+ * 우리 쪽    SENT 84건        보냈다
+ * 받는 쪽    저널 17건        앉았다
+ * 그 차이    아무 데도 없다
+ * ```
+ *
+ * 세 번 다 사람이 손으로 세서 찾았다. 담김이 보류로 남은 것, 재고 둘이 수량 0 으로 거절된 것, 어휘가
+ * 안 나간 것 — **다음엔 아무도 안 센다.**
+ *
+ * ── `SENT` 는 「보냈다」이지 「앉았다」가 아니다 ────────────────────────────
+ * 받는 쪽이 `accepted` 로 답하는 것은 **접수했다**는 뜻이다. 그 뒤에 되풀이로 합쳐지거나, 리듀서가
+ * 못 읽거나, 표준 밖 값이라 버려질 수 있다. 그 셋 다 우리에게는 `SENT` 로 보인다.
+ *
+ * ── **넷으로 가른다. 둘로는 안 닫힌다** ────────────────────────────────────
+ * 처음에는 「앉았다 · 거절됐다」 둘로 뺐다. 그러면 이렇게 된다.
+ *
+ * ```
+ * 둘로   157 − 46 − 2 = 109 「사라졌다」     ← 진실은 되풀이 108 + 어휘 1
+ * 넷으로 157 − 46 − 2 − 108 − 1 = 0
+ * ```
+ *
+ * **109를 「사라졌다」로 내면 그날부터 아무도 그 수를 안 본다.** 늘 큰 수가 떠 있으면 진짜로 하나
+ * 사라진 날을 못 본다 — 경보를 울려 놓고 아무도 안 듣게 만드는 것이 안 울리는 것보다 나쁘다.
+ *
+ * 인티그레이션이 실제 수로 짚었다(2026-09-05). 108은 대부분 **되풀이**였고, 그것은 우리가 같은
+ * 실적을 다시 보낸 것을 받는 쪽이 옳게 합친 결과다 — 사라진 것이 아니다.
+ *
+ * ```
+ * landed       저널에 앉았다
+ * rejected     받는 쪽이 안 받는다고 말했다      우리가 안다
+ * duplicates   이미 있는 사실이라 합쳤다         우리가 다시 보낸 것이다
+ * vocabulary   저널에 안 가는 어휘다             설계대로다
+ * ```
+ *
+ * ── 「모른다」를 「맞다」로 읽지 않는다 ─────────────────────────────────────
+ * **이 모듈의 요점이다.** 받는 쪽 수를 못 물어보면 답은 「맞다」가 아니라 **「모른다」**다. 0 으로
+ * 채우거나 우리 수를 그대로 두 번 쓰면, 맞춰 보는 자리를 만들어 놓고 **늘 초록인 자리**를 만든 것이다.
+ *
+ * 오늘 하루 종일 잡은 그 부류를, 그것을 잡으려고 만든 자리에서 다시 만들지 않는다.
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+export type ReconcileVerdict = 
+/** 두 수가 같다. */
+'matched'
+/** 보낸 것보다 앉은 것이 적다 — **사실이 사라졌다.** */
+ | 'short'
+/**
+ * 앉은 것이 더 많다 — **원인이 둘이고, 지금 이 셈은 둘을 못 가른다.**
+ *
+ * ```
+ * ① 같은 사실이 두 번 앉았다        받는 쪽 dedupe 가 놓친 재전송
+ * ② 받는 쪽이 스스로 넣은 행이다     우리 봉투가 없는 행. period fact backfill 이 그렇게 넣는다
+ * ```
+ *
+ * ②는 셈이 정상인데 음수가 나는 경우다 — 그 구간을 맞춰 보면 그만큼 많이 나오는 것이 맞다.
+ * 그래서 이 판정을 「정상일 수도 있다」로 읽으면 ①도 ②도 안 찾게 된다.
+ *
+ * 가르려면 저널 행에 「어떻게 들어왔나」가 있어야 하는데 없다(인티그레이션 실측 2026-09-10 —
+ * ingest 함수 열이 record 하나에 event 하나만 내고, 저널을 쓰는 문 둘이 다 `.map()` 이라
+ * **봉투 하나가 사실 여럿을 내는 경로는 없다**).
+ */
+ | 'excess'
+/** 받는 쪽 수를 모른다. **맞다가 아니다.** */
+ | 'unknown';
+export interface ReconcileInput {
+    /** 우리가 보냈다고 표시한 수. */
+    sent: number;
+    /**
+     * 받는 쪽에 앉은 수. **못 물어봤으면 `undefined`** — 0 이 아니다.
+     *
+     * 0 은 「하나도 안 앉았다」이고 그것은 심각한 사실이다. 모르는 것과 섞으면 진짜 0 이 묻힌다.
+     */
+    landed?: number;
+    /** 받는 쪽이 거절한다고 답한 수 — 이건 우리가 안다. 사라진 것이 아니라 **거절된 것**이다. */
+    rejected?: number;
+    /**
+     * 이미 있는 사실이라 합쳐진 수. **우리가 다시 보낸 것**이지 사라진 것이 아니다.
+     *
+     * 이 값을 안 빼면 되풀이가 통째로 「사라졌다」로 세어진다 — 오늘 108건이 그랬다.
+     */
+    duplicates?: number;
+    /**
+     * 저널에 안 가는 어휘(`MasterDataRecord`)의 수. **설계대로 안 가는 것**이다.
+     *
+     * 이건 우리가 안다 — 우리가 낸 봉투이므로 세어 둘 수 있다. 받는 쪽에 묻지 않아도 된다.
+     */
+    vocabulary?: number;
+}
+export interface Reconciliation {
+    verdict: ReconcileVerdict;
+    /** 설명되지 않는 차이. 모르면 `undefined`. */
+    unexplained?: number;
+    sent: number;
+    landed?: number;
+    rejected: number;
+    duplicates: number;
+    vocabulary: number;
+}
+/**
+ * 두 수를 맞춘다.
+ *
+ * **거절된 것은 사라진 것이 아니다.** 받는 쪽이 「안 받는다」고 말했고 우리는 그것을 안다. 그것까지
+ * 「사라졌다」로 세면 진짜 조용히 없어진 것이 그 수에 묻힌다.
+ */
+export declare function reconcile(input: ReconcileInput): Reconciliation;
+/** 사람이 읽는 한 줄 — 표에 그대로 걸 수 있게. */
+export declare function describeReconciliation(found: Reconciliation, where: string): string;

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

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * **보낸 수와 앉은 수를 맞춰 본다** — 순수 판단.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * ── 오늘 이것이 없어서 무슨 일이 났나 ──────────────────────────────────────
+ * 2026-09-05 하루에 세 번, 사실이 안 갔는데 **양쪽 다 초록**이었다.
+ *
+ * ```
+ * 우리 쪽    SENT 84건        보냈다
+ * 받는 쪽    저널 17건        앉았다
+ * 그 차이    아무 데도 없다
+ * ```
+ *
+ * 세 번 다 사람이 손으로 세서 찾았다. 담김이 보류로 남은 것, 재고 둘이 수량 0 으로 거절된 것, 어휘가
+ * 안 나간 것 — **다음엔 아무도 안 센다.**
+ *
+ * ── `SENT` 는 「보냈다」이지 「앉았다」가 아니다 ────────────────────────────
+ * 받는 쪽이 `accepted` 로 답하는 것은 **접수했다**는 뜻이다. 그 뒤에 되풀이로 합쳐지거나, 리듀서가
+ * 못 읽거나, 표준 밖 값이라 버려질 수 있다. 그 셋 다 우리에게는 `SENT` 로 보인다.
+ *
+ * ── **넷으로 가른다. 둘로는 안 닫힌다** ────────────────────────────────────
+ * 처음에는 「앉았다 · 거절됐다」 둘로 뺐다. 그러면 이렇게 된다.
+ *
+ * ```
+ * 둘로   157 − 46 − 2 = 109 「사라졌다」     ← 진실은 되풀이 108 + 어휘 1
+ * 넷으로 157 − 46 − 2 − 108 − 1 = 0
+ * ```
+ *
+ * **109를 「사라졌다」로 내면 그날부터 아무도 그 수를 안 본다.** 늘 큰 수가 떠 있으면 진짜로 하나
+ * 사라진 날을 못 본다 — 경보를 울려 놓고 아무도 안 듣게 만드는 것이 안 울리는 것보다 나쁘다.
+ *
+ * 인티그레이션이 실제 수로 짚었다(2026-09-05). 108은 대부분 **되풀이**였고, 그것은 우리가 같은
+ * 실적을 다시 보낸 것을 받는 쪽이 옳게 합친 결과다 — 사라진 것이 아니다.
+ *
+ * ```
+ * landed       저널에 앉았다
+ * rejected     받는 쪽이 안 받는다고 말했다      우리가 안다
+ * duplicates   이미 있는 사실이라 합쳤다         우리가 다시 보낸 것이다
+ * vocabulary   저널에 안 가는 어휘다             설계대로다
+ * ```
+ *
+ * ── 「모른다」를 「맞다」로 읽지 않는다 ─────────────────────────────────────
+ * **이 모듈의 요점이다.** 받는 쪽 수를 못 물어보면 답은 「맞다」가 아니라 **「모른다」**다. 0 으로
+ * 채우거나 우리 수를 그대로 두 번 쓰면, 맞춰 보는 자리를 만들어 놓고 **늘 초록인 자리**를 만든 것이다.
+ *
+ * 오늘 하루 종일 잡은 그 부류를, 그것을 잡으려고 만든 자리에서 다시 만들지 않는다.
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconcile = reconcile;
+exports.describeReconciliation = describeReconciliation;
+/**
+ * 두 수를 맞춘다.
+ *
+ * **거절된 것은 사라진 것이 아니다.** 받는 쪽이 「안 받는다」고 말했고 우리는 그것을 안다. 그것까지
+ * 「사라졌다」로 세면 진짜 조용히 없어진 것이 그 수에 묻힌다.
+ */
+function reconcile(input) {
+    const rejected = Math.max(0, input.rejected ?? 0);
+    const duplicates = Math.max(0, input.duplicates ?? 0);
+    const vocabulary = Math.max(0, input.vocabulary ?? 0);
+    const sent = Math.max(0, input.sent);
+    if (!Number.isFinite(input.landed)) {
+        /* 못 물어봤다. **맞다고 하지 않는다.** */
+        return { verdict: 'unknown', sent, rejected, duplicates, vocabulary };
+    }
+    const landed = Math.max(0, input.landed);
+    /*
+     * 앉아야 할 수 = 보낸 것 − (거절 + 되풀이 + 어휘).
+     *
+     * 셋 다 **우리가 아는 이유**다. 빼지 않으면 아는 것까지 「사라졌다」로 세어지고, 그러면 그 수를
+     * 아무도 안 보게 된다(머리말).
+     */
+    const expected = Math.max(0, sent - rejected - duplicates - vocabulary);
+    const unexplained = expected - landed;
+    if (unexplained === 0) {
+        return { verdict: 'matched', unexplained: 0, sent, landed, rejected, duplicates, vocabulary };
+    }
+    return {
+        verdict: unexplained > 0 ? 'short' : 'excess',
+        unexplained,
+        sent,
+        landed,
+        rejected,
+        duplicates,
+        vocabulary
+    };
+}
+/** 사람이 읽는 한 줄 — 표에 그대로 걸 수 있게. */
+function describeReconciliation(found, where) {
+    switch (found.verdict) {
+        case 'unknown':
+            return (`${where}: 보낸 ${found.sent}건. 받는 쪽에 몇 건이 앉았는지 **묻지 못했습니다** — ` +
+                '맞는지 안 맞는지 알 수 없습니다');
+        case 'matched':
+            return `${where}: 보낸 ${found.sent}건이 모두 설명됩니다 — 앉음 ${found.landed}${aside(found)}`;
+        case 'short':
+            return (`${where}: **${found.unexplained}건이 사라졌습니다** — 보낸 ${found.sent}건 중 앉은 것이 ` +
+                `${found.landed}건입니다${aside(found)}. 거절도 되풀이도 어휘도 아닌데 안 앉았습니다`);
+        case 'excess':
+            return (`${where}: 앉은 것이 ${-found.unexplained}건 많습니다 — 보낸 ${found.sent}건, 앉은 ${found.landed}건. ` +
+                '같은 사실이 두 번 앉았거나, 받는 쪽이 우리 봉투 없이 스스로 넣은 행입니다');
+    }
+}
+/** 아는 이유들 — 사라진 수와 섞이지 않게 괄호로 따로 적는다. */
+function aside(found) {
+    const known = [
+        found.rejected ? `거절 ${found.rejected}` : '',
+        found.duplicates ? `되풀이 ${found.duplicates}` : '',
+        found.vocabulary ? `어휘 ${found.vocabulary}` : ''
+    ].filter(Boolean);
+    return known.length ? ` (${known.join(' · ')} 은 뺀 수입니다)` : '';
+}
+//# sourceMappingURL=reconciliation.js.map