@things-factory/webhook 10.1.29 → 10.1.33

package/dist-server/service/index.d.ts

@@ -2,3 +2,19 @@ export * from './webhook-destination/webhook-destination';
 export * from './webhook-destination/webhook-destination-resolver';
 export * from './webhook-outbox-event/webhook-outbox-event';
 export * from './webhook-sequence/webhook-sequence';
+export * from './outbox/delivery';
+export * from './outbox/settlement';
+export * from './outbox/row-effect';
+export * from './outbox/seq-report';
+export * from './outbox/reconciliation';
+export * from './outbox/standing';
+export * from './outbox/requeue-note';
+export * from './outbox/page';
+export * from './outbox/writing-transaction';
+export * from './outbox/append';
+export * from './outbox/pump-gate';
+export * from './observability/clock-offset';
+export * from './observability/trace-context';
+export * from './outbox/store';
+export * from './outbox/dispatcher';
+export * from './outbox/webhook-store';

package/dist-server/service/index.js

@@ -14,4 +14,32 @@ tslib_1.__exportStar(require("./webhook-destination/webhook-destination"), expor
 tslib_1.__exportStar(require("./webhook-destination/webhook-destination-resolver"), exports);
 tslib_1.__exportStar(require("./webhook-outbox-event/webhook-outbox-event"), exports);
 tslib_1.__exportStar(require("./webhook-sequence/webhook-sequence"), exports);
+/*
+ * The outbox machine, moved from operato-plant (ADR-0078 decision 2). Step ①: the pure judgement —
+ * envelope, signature, reading the receiver's answer, settlement, what an answer does to our rows,
+ * the sequence report, reconciliation, standing. None of these touch a store.
+ */
+tslib_1.__exportStar(require("./outbox/delivery"), exports);
+tslib_1.__exportStar(require("./outbox/settlement"), exports);
+tslib_1.__exportStar(require("./outbox/row-effect"), exports);
+tslib_1.__exportStar(require("./outbox/seq-report"), exports);
+tslib_1.__exportStar(require("./outbox/reconciliation"), exports);
+tslib_1.__exportStar(require("./outbox/standing"), exports);
+tslib_1.__exportStar(require("./outbox/requeue-note"), exports);
+tslib_1.__exportStar(require("./outbox/page"), exports);
+tslib_1.__exportStar(require("./outbox/writing-transaction"), exports);
+/*
+ * Step ②: the back row. Writing a fact down takes the caller's open transaction - in the type, not only
+ * in a check - because the number and the row have to commit together or the number burns.
+ */
+tslib_1.__exportStar(require("./outbox/append"), exports);
+tslib_1.__exportStar(require("./outbox/pump-gate"), exports);
+/* What a delivery needs to say "when" and "which request" — moved from operato-plant with the dispatcher's
+ * needs in mind (ADR-0078 decision 1). The inbound side reads the same two. */
+tslib_1.__exportStar(require("./observability/clock-offset"), exports);
+tslib_1.__exportStar(require("./observability/trace-context"), exports);
+/* Step ②: the back row. One dispatcher over a store interface; `webhookStore` is this module's own store. */
+tslib_1.__exportStar(require("./outbox/store"), exports);
+tslib_1.__exportStar(require("./outbox/dispatcher"), exports);
+tslib_1.__exportStar(require("./outbox/webhook-store"), exports);
 //# sourceMappingURL=index.js.map

package/dist-server/service/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../server/service/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,oFAAyD;AACzD,6FAAkE;AAClE,sFAA2D;AAC3D,8EAAmD","sourcesContent":["/*\n * Each source file is named rather than re-exporting folder barrels.\n *\n * A name added to a folder barrel but not listed here stops at the package boundary, and the\n * consumer's error is `TS2305: has no exported member` — which reads like the name does not\n * exist rather than like it is unreachable. That happened on 2026-09-07 with\n * `work-shift/days-of-week`: the parser was in the folder barrel, not here, and the consuming\n * lane wrote its own until the miss was found.\n */\nexport * from './webhook-destination/webhook-destination'\nexport * from './webhook-destination/webhook-destination-resolver'\nexport * from './webhook-outbox-event/webhook-outbox-event'\nexport * from './webhook-sequence/webhook-sequence'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../server/service/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,oFAAyD;AACzD,6FAAkE;AAClE,sFAA2D;AAC3D,8EAAmD;AAEnD;;;;GAIG;AACH,4DAAiC;AACjC,8DAAmC;AACnC,8DAAmC;AACnC,8DAAmC;AACnC,kEAAuC;AACvC,4DAAiC;AACjC,gEAAqC;AACrC,wDAA6B;AAC7B,uEAA4C;AAE5C;;;GAGG;AACH,0DAA+B;AAC/B,6DAAkC;AAElC;+EAC+E;AAC/E,uEAA4C;AAC5C,wEAA6C;AAE7C,6GAA6G;AAC7G,yDAA8B;AAC9B,8DAAmC;AACnC,iEAAsC","sourcesContent":["/*\n * Each source file is named rather than re-exporting folder barrels.\n *\n * A name added to a folder barrel but not listed here stops at the package boundary, and the\n * consumer's error is `TS2305: has no exported member` — which reads like the name does not\n * exist rather than like it is unreachable. That happened on 2026-09-07 with\n * `work-shift/days-of-week`: the parser was in the folder barrel, not here, and the consuming\n * lane wrote its own until the miss was found.\n */\nexport * from './webhook-destination/webhook-destination'\nexport * from './webhook-destination/webhook-destination-resolver'\nexport * from './webhook-outbox-event/webhook-outbox-event'\nexport * from './webhook-sequence/webhook-sequence'\n\n/*\n * The outbox machine, moved from operato-plant (ADR-0078 decision 2). Step ①: the pure judgement —\n * envelope, signature, reading the receiver's answer, settlement, what an answer does to our rows,\n * the sequence report, reconciliation, standing. None of these touch a store.\n */\nexport * from './outbox/delivery'\nexport * from './outbox/settlement'\nexport * from './outbox/row-effect'\nexport * from './outbox/seq-report'\nexport * from './outbox/reconciliation'\nexport * from './outbox/standing'\nexport * from './outbox/requeue-note'\nexport * from './outbox/page'\nexport * from './outbox/writing-transaction'\n\n/*\n * Step ②: the back row. Writing a fact down takes the caller's open transaction - in the type, not only\n * in a check - because the number and the row have to commit together or the number burns.\n */\nexport * from './outbox/append'\nexport * from './outbox/pump-gate'\n\n/* What a delivery needs to say \"when\" and \"which request\" — moved from operato-plant with the dispatcher's\n * needs in mind (ADR-0078 decision 1). The inbound side reads the same two. */\nexport * from './observability/clock-offset'\nexport * from './observability/trace-context'\n\n/* Step ②: the back row. One dispatcher over a store interface; `webhookStore` is this module's own store. */\nexport * from './outbox/store'\nexport * from './outbox/dispatcher'\nexport * from './outbox/webhook-store'\n\n"]}

package/dist-server/service/observability/clock-offset.d.ts

@@ -0,0 +1,88 @@
+/**
+ * How far our clock has drifted from the systems we exchange records with.
+ *
+ * ── Why this is worth measuring ────────────────────────────────────────────
+ * Every record we keep is stamped by this server's clock, and the audit trail
+ * is only worth anything if that clock is right. Nothing here can check that
+ * against a reference clock -- keeping the host in step with one is the host's
+ * job, not the application's.
+ *
+ * But we are not without evidence. Every signed exchange carries the other
+ * side's timestamp, so each one is a reading of the difference between two
+ * clocks. We were throwing that away.
+ *
+ * ── What goes wrong when it drifts ─────────────────────────────────────────
+ * The signature check refuses a timestamp more than five minutes from now, in
+ * either direction. So a clock that slips past that does not degrade: every
+ * exchange in both directions turns into 401 at once, and the message says the
+ * webhook was rejected, which reads like a secret problem. Somebody then
+ * checks the secret, finds it right, and looks somewhere else.
+ *
+ * That is why the middle band exists. Half the tolerance is still working, and
+ * it is the only chance to say something before everything stops.
+ *
+ * ── What this is not ───────────────────────────────────────────────────────
+ * It is not a time source and it does not correct anything. A reading says the
+ * two clocks disagree; it cannot say which one is wrong. Both are reported so
+ * a person can go and look.
+ */
+/** Where a reading came from. Kept so a report can name the peer rather than an average. */
+export interface ClockReading {
+    /** The system on the other side, as we know it -- a site id or a destination name. */
+    peer: string;
+    /**
+     * Our clock minus theirs, in milliseconds.
+     *
+     * Positive means we are ahead of them. The sign is kept because it is the
+     * first thing anyone asks, and an absolute value cannot be added back.
+     */
+    offsetMs: number;
+    /** When we took the reading, by our clock. */
+    atMs: number;
+}
+export type ClockStanding = 
+/** Comfortably within what the signature check allows. */
+'in-step'
+/** Still working, but past half the tolerance -- this is the warning band. */
+ | 'drifting'
+/** Beyond what the signature check allows: exchanges are failing right now. */
+ | 'out-of-step';
+/**
+ * How bad a reading is, against the tolerance the signature check actually uses.
+ *
+ * The threshold is not a number picked here. It is the same constant the
+ * contract refuses timestamps by, so "out-of-step" means precisely "this is
+ * already being rejected" rather than an opinion about how much drift is too
+ * much.
+ */
+export declare function clockStanding(offsetMs: number, toleranceMs?: number): ClockStanding;
+/**
+ * The reading to report for a peer, given everything seen from it.
+ *
+ * The most recent one, not the worst. A clock that was wrong and has been put
+ * right should stop being reported as wrong -- otherwise the fix cannot be
+ * seen to have worked, and the report has to be cleared by hand, which means
+ * it will not be.
+ */
+export declare function latestOf(readings: readonly ClockReading[], peer: string): ClockReading | undefined;
+/**
+ * The single reading that best answers "is this server's clock trustworthy".
+ *
+ * The furthest-off peer among the current readings. One peer disagreeing is
+ * that peer's problem; every peer disagreeing by about the same amount is
+ * ours, and either way the largest one is what a person needs to see first.
+ */
+export declare function worstOf(readings: readonly ClockReading[]): ClockReading | undefined;
+/**
+ * Read a peer's timestamp header into an offset.
+ *
+ * Anything unreadable gives back nothing rather than zero. Zero is the value
+ * that means "the clocks agree perfectly", which is the one thing a header we
+ * could not parse never tells us.
+ */
+export declare function offsetFrom(theirTimestamp: string | undefined, ourMs: number): number | undefined;
+/** Record one reading. Peers we have not heard from in this process are simply absent. */
+export declare function noteClockReading(peer: string, offsetMs: number | undefined, atMs?: number): void;
+export declare function clockReadings(): ClockReading[];
+/** For tests and restarts -- a reading from a previous run says nothing about this clock. */
+export declare function forgetClockReadings(): void;

package/dist-server/service/observability/clock-offset.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clockStanding = clockStanding;
+exports.latestOf = latestOf;
+exports.worstOf = worstOf;
+exports.offsetFrom = offsetFrom;
+exports.noteClockReading = noteClockReading;
+exports.clockReadings = clockReadings;
+exports.forgetClockReadings = forgetClockReadings;
+const webhook_1 = require("@operato/ops-contract/webhook");
+/**
+ * How bad a reading is, against the tolerance the signature check actually uses.
+ *
+ * The threshold is not a number picked here. It is the same constant the
+ * contract refuses timestamps by, so "out-of-step" means precisely "this is
+ * already being rejected" rather than an opinion about how much drift is too
+ * much.
+ */
+function clockStanding(offsetMs, toleranceMs = webhook_1.WEBHOOK_TOLERANCE_MS) {
+    const off = Math.abs(offsetMs);
+    if (off >= toleranceMs) {
+        return 'out-of-step';
+    }
+    return off >= toleranceMs / 2 ? 'drifting' : 'in-step';
+}
+/**
+ * The reading to report for a peer, given everything seen from it.
+ *
+ * The most recent one, not the worst. A clock that was wrong and has been put
+ * right should stop being reported as wrong -- otherwise the fix cannot be
+ * seen to have worked, and the report has to be cleared by hand, which means
+ * it will not be.
+ */
+function latestOf(readings, peer) {
+    let latest;
+    for (const reading of readings) {
+        if (reading.peer === peer && (!latest || reading.atMs > latest.atMs)) {
+            latest = reading;
+        }
+    }
+    return latest;
+}
+/**
+ * The single reading that best answers "is this server's clock trustworthy".
+ *
+ * The furthest-off peer among the current readings. One peer disagreeing is
+ * that peer's problem; every peer disagreeing by about the same amount is
+ * ours, and either way the largest one is what a person needs to see first.
+ */
+function worstOf(readings) {
+    let worst;
+    for (const reading of readings) {
+        if (!worst || Math.abs(reading.offsetMs) > Math.abs(worst.offsetMs)) {
+            worst = reading;
+        }
+    }
+    return worst;
+}
+/**
+ * Read a peer's timestamp header into an offset.
+ *
+ * Anything unreadable gives back nothing rather than zero. Zero is the value
+ * that means "the clocks agree perfectly", which is the one thing a header we
+ * could not parse never tells us.
+ */
+function offsetFrom(theirTimestamp, ourMs) {
+    if (!theirTimestamp) {
+        return undefined;
+    }
+    const theirs = Date.parse(theirTimestamp);
+    return Number.isFinite(theirs) ? ourMs - theirs : undefined;
+}
+/*
+ * ── The readings themselves ────────────────────────────────────────────────
+ * Held per process and not written down. A clock offset is only meaningful for
+ * about as long as it takes to read it, so persisting it would mostly serve to
+ * report a drift that has already been fixed. Each instance answers for the
+ * clock it is actually stamping records with, which is the honest thing for a
+ * process to report about itself.
+ */
+const readings = new Map();
+/** Record one reading. Peers we have not heard from in this process are simply absent. */
+function noteClockReading(peer, offsetMs, atMs = Date.now()) {
+    if (offsetMs === undefined) {
+        return;
+    }
+    readings.set(peer, { peer, offsetMs, atMs });
+}
+function clockReadings() {
+    return [...readings.values()];
+}
+/** For tests and restarts -- a reading from a previous run says nothing about this clock. */
+function forgetClockReadings() {
+    readings.clear();
+}
+//# sourceMappingURL=clock-offset.js.map

package/dist-server/service/observability/clock-offset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock-offset.js","sourceRoot":"","sources":["../../../server/service/observability/clock-offset.ts"],"names":[],"mappings":";;AA8DA,sCAQC;AAUD,4BAUC;AASD,0BAUC;AASD,gCAQC;AAaD,4CAMC;AAED,sCAEC;AAGD,kDAEC;AA1JD,2DAAoE;AAsDpE;;;;;;;GAOG;AACH,SAAgB,aAAa,CAAC,QAAgB,EAAE,cAAsB,8BAAoB;IACxF,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAE9B,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;QACvB,OAAO,aAAa,CAAA;IACtB,CAAC;IAED,OAAO,GAAG,IAAI,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAA;AACxD,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,QAAQ,CAAC,QAAiC,EAAE,IAAY;IACtE,IAAI,MAAgC,CAAA;IAEpC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,IAAI,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YACrE,MAAM,GAAG,OAAO,CAAA;QAClB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,OAAO,CAAC,QAAiC;IACvD,IAAI,KAA+B,CAAA;IAEnC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YACpE,KAAK,GAAG,OAAO,CAAA;QACjB,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,cAAkC,EAAE,KAAa;IAC1E,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAA;IAEzC,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,SAAS,CAAA;AAC7D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAA;AAEhD,0FAA0F;AAC1F,SAAgB,gBAAgB,CAAC,IAAY,EAAE,QAA4B,EAAE,OAAe,IAAI,CAAC,GAAG,EAAE;IACpG,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAM;IACR,CAAC;IAED,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;AAC9C,CAAC;AAED,SAAgB,aAAa;IAC3B,OAAO,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;AAC/B,CAAC;AAED,6FAA6F;AAC7F,SAAgB,mBAAmB;IACjC,QAAQ,CAAC,KAAK,EAAE,CAAA;AAClB,CAAC","sourcesContent":["import { WEBHOOK_TOLERANCE_MS } from '@operato/ops-contract/webhook'\n\n/**\n * How far our clock has drifted from the systems we exchange records with.\n *\n * ── Why this is worth measuring ────────────────────────────────────────────\n * Every record we keep is stamped by this server's clock, and the audit trail\n * is only worth anything if that clock is right. Nothing here can check that\n * against a reference clock -- keeping the host in step with one is the host's\n * job, not the application's.\n *\n * But we are not without evidence. Every signed exchange carries the other\n * side's timestamp, so each one is a reading of the difference between two\n * clocks. We were throwing that away.\n *\n * ── What goes wrong when it drifts ─────────────────────────────────────────\n * The signature check refuses a timestamp more than five minutes from now, in\n * either direction. So a clock that slips past that does not degrade: every\n * exchange in both directions turns into 401 at once, and the message says the\n * webhook was rejected, which reads like a secret problem. Somebody then\n * checks the secret, finds it right, and looks somewhere else.\n *\n * That is why the middle band exists. Half the tolerance is still working, and\n * it is the only chance to say something before everything stops.\n *\n * ── What this is not ───────────────────────────────────────────────────────\n * It is not a time source and it does not correct anything. A reading says the\n * two clocks disagree; it cannot say which one is wrong. Both are reported so\n * a person can go and look.\n */\n\n/** Where a reading came from. Kept so a report can name the peer rather than an average. */\nexport interface ClockReading {\n  /** The system on the other side, as we know it -- a site id or a destination name. */\n  peer: string\n  /**\n   * Our clock minus theirs, in milliseconds.\n   *\n   * Positive means we are ahead of them. The sign is kept because it is the\n   * first thing anyone asks, and an absolute value cannot be added back.\n   */\n  offsetMs: number\n  /** When we took the reading, by our clock. */\n  atMs: number\n}\n\nexport type ClockStanding =\n  /** Comfortably within what the signature check allows. */\n  | 'in-step'\n  /** Still working, but past half the tolerance -- this is the warning band. */\n  | 'drifting'\n  /** Beyond what the signature check allows: exchanges are failing right now. */\n  | 'out-of-step'\n\n/**\n * How bad a reading is, against the tolerance the signature check actually uses.\n *\n * The threshold is not a number picked here. It is the same constant the\n * contract refuses timestamps by, so \"out-of-step\" means precisely \"this is\n * already being rejected\" rather than an opinion about how much drift is too\n * much.\n */\nexport function clockStanding(offsetMs: number, toleranceMs: number = WEBHOOK_TOLERANCE_MS): ClockStanding {\n  const off = Math.abs(offsetMs)\n\n  if (off >= toleranceMs) {\n    return 'out-of-step'\n  }\n\n  return off >= toleranceMs / 2 ? 'drifting' : 'in-step'\n}\n\n/**\n * The reading to report for a peer, given everything seen from it.\n *\n * The most recent one, not the worst. A clock that was wrong and has been put\n * right should stop being reported as wrong -- otherwise the fix cannot be\n * seen to have worked, and the report has to be cleared by hand, which means\n * it will not be.\n */\nexport function latestOf(readings: readonly ClockReading[], peer: string): ClockReading | undefined {\n  let latest: ClockReading | undefined\n\n  for (const reading of readings) {\n    if (reading.peer === peer && (!latest || reading.atMs > latest.atMs)) {\n      latest = reading\n    }\n  }\n\n  return latest\n}\n\n/**\n * The single reading that best answers \"is this server's clock trustworthy\".\n *\n * The furthest-off peer among the current readings. One peer disagreeing is\n * that peer's problem; every peer disagreeing by about the same amount is\n * ours, and either way the largest one is what a person needs to see first.\n */\nexport function worstOf(readings: readonly ClockReading[]): ClockReading | undefined {\n  let worst: ClockReading | undefined\n\n  for (const reading of readings) {\n    if (!worst || Math.abs(reading.offsetMs) > Math.abs(worst.offsetMs)) {\n      worst = reading\n    }\n  }\n\n  return worst\n}\n\n/**\n * Read a peer's timestamp header into an offset.\n *\n * Anything unreadable gives back nothing rather than zero. Zero is the value\n * that means \"the clocks agree perfectly\", which is the one thing a header we\n * could not parse never tells us.\n */\nexport function offsetFrom(theirTimestamp: string | undefined, ourMs: number): number | undefined {\n  if (!theirTimestamp) {\n    return undefined\n  }\n\n  const theirs = Date.parse(theirTimestamp)\n\n  return Number.isFinite(theirs) ? ourMs - theirs : undefined\n}\n\n/*\n * ── The readings themselves ────────────────────────────────────────────────\n * Held per process and not written down. A clock offset is only meaningful for\n * about as long as it takes to read it, so persisting it would mostly serve to\n * report a drift that has already been fixed. Each instance answers for the\n * clock it is actually stamping records with, which is the honest thing for a\n * process to report about itself.\n */\nconst readings = new Map<string, ClockReading>()\n\n/** Record one reading. Peers we have not heard from in this process are simply absent. */\nexport function noteClockReading(peer: string, offsetMs: number | undefined, atMs: number = Date.now()): void {\n  if (offsetMs === undefined) {\n    return\n  }\n\n  readings.set(peer, { peer, offsetMs, atMs })\n}\n\nexport function clockReadings(): ClockReading[] {\n  return [...readings.values()]\n}\n\n/** For tests and restarts -- a reading from a previous run says nothing about this clock. */\nexport function forgetClockReadings(): void {\n  readings.clear()\n}\n"]}

package/dist-server/service/observability/trace-context.d.ts

@@ -0,0 +1,66 @@
+/**
+ * **한 사실이 어디를 지났는지 잇는 값** — W3C Trace Context 의 `traceparent`.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * ── 무엇이 없어서 무엇이 아팠나 ────────────────────────────────────────────
+ * 실적 하나가 MES 에서 트윈까지 가는 데 다섯 봉투가 나간다. 그중 하나가 안 앉으면 **양쪽 로그를
+ * 사람이 눈으로 맞춰야 한다.**
+ *
+ * 실제로 그랬다(2026-09-05). 봉투가 저널에 앉았는지 확인하려고 두 사람이 `seq` 와 밀리초 시각으로
+ * 대조했고, 한 건이 조용히 합쳐진 것을 찾는 데 그 대조가 전부였다. 잇는 값이 있었으면 한 번에 찾았다.
+ *
+ * ── 왜 우리 것을 짓지 않나 ─────────────────────────────────────────────────
+ * W3C 가 이미 정했고(Trace Context Level 1), 모든 수집기가 그 이름으로 읽는다. 우리 이름으로 지으면
+ * 우리 로그에서만 이어지고 그 밖에서는 아무 뜻이 없다.
+ *
+ * ```
+ * traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+ *              ^^ ^──────── trace-id ────────────^ ^─ parent-id ─^ ^^ flags
+ *              버전         한 흐름 전체를 가리킨다   이 구간         샘플 여부
+ * ```
+ *
+ * ── 받은 것을 이어 간다. 없으면 시작한다 ───────────────────────────────────
+ * 부르는 쪽이 값을 주면 **그 흐름을 잇는다**(`trace-id` 를 유지하고 구간만 새로 딴다). 안 주면 우리가
+ * 시작한 흐름이다.
+ *
+ * ── 모양이 이상하면 **잇지 않고 새로 시작한다** ────────────────────────────
+ * 남이 준 값을 검사 없이 실어 보내면 우리 로그에 남의 형식이 섞이고, 수집기가 그 줄을 통째로 버린다.
+ * 그러면 **추적을 붙였는데 아무것도 안 이어지는** 상태가 된다 — 안 붙인 것보다 나쁘다.
+ *
+ * 전부 0인 값도 규격이 금지한다(§3.2.2.3). 그것을 이으면 서로 다른 흐름이 한 덩어리가 된다.
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+/** W3C 가 정한 헤더 이름. 소문자다. */
+export declare const TRACEPARENT = "traceparent";
+export interface TraceContext {
+    /** 한 흐름 전체 — 32자리 16진수. 실적 하나가 트윈까지 가는 동안 같은 값이다. */
+    traceId: string;
+    /** 이 구간 — 16자리 16진수. 봉투마다 새로 딴다. */
+    spanId: string;
+    /** 부르는 쪽이 준 값을 이었나. 거짓이면 우리가 시작한 흐름이다. */
+    continued: boolean;
+}
+/**
+ * 받은 헤더에서 **이을 수 있는 흐름**만 꺼낸다.
+ *
+ * 못 이으면 `undefined` — 부르는 쪽이 그때 새로 시작한다. **고쳐서 쓰지 않는다**(머리말).
+ */
+export declare function parseTraceparent(header: unknown): {
+    traceId: string;
+    spanId: string;
+} | undefined;
+/**
+ * 이 구간의 추적 값을 만든다.
+ *
+ * `incoming` 이 이을 수 있으면 그 흐름을 잇고, 아니면 새로 시작한다.
+ */
+export declare function traceFor(incoming: unknown, random?: () => string): TraceContext;
+/** 내보낼 헤더 값. 받는 쪽이 이것을 이어 간다. */
+export declare function toTraceparent(trace: TraceContext): string;
+/**
+ * 로그에 붙일 짧은 표시.
+ *
+ * 32자리를 매 줄에 적으면 사람이 안 읽는다. 앞 8자리면 한 서버의 하루 안에서 충분히 갈린다 —
+ * **대조용이지 식별자가 아니다.** 정확히 이을 때는 전체 값을 쓴다.
+ */
+export declare function traceTag(trace: TraceContext): string;

package/dist-server/service/observability/trace-context.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * **한 사실이 어디를 지났는지 잇는 값** — W3C Trace Context 의 `traceparent`.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * ── 무엇이 없어서 무엇이 아팠나 ────────────────────────────────────────────
+ * 실적 하나가 MES 에서 트윈까지 가는 데 다섯 봉투가 나간다. 그중 하나가 안 앉으면 **양쪽 로그를
+ * 사람이 눈으로 맞춰야 한다.**
+ *
+ * 실제로 그랬다(2026-09-05). 봉투가 저널에 앉았는지 확인하려고 두 사람이 `seq` 와 밀리초 시각으로
+ * 대조했고, 한 건이 조용히 합쳐진 것을 찾는 데 그 대조가 전부였다. 잇는 값이 있었으면 한 번에 찾았다.
+ *
+ * ── 왜 우리 것을 짓지 않나 ─────────────────────────────────────────────────
+ * W3C 가 이미 정했고(Trace Context Level 1), 모든 수집기가 그 이름으로 읽는다. 우리 이름으로 지으면
+ * 우리 로그에서만 이어지고 그 밖에서는 아무 뜻이 없다.
+ *
+ * ```
+ * traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+ *              ^^ ^──────── trace-id ────────────^ ^─ parent-id ─^ ^^ flags
+ *              버전         한 흐름 전체를 가리킨다   이 구간         샘플 여부
+ * ```
+ *
+ * ── 받은 것을 이어 간다. 없으면 시작한다 ───────────────────────────────────
+ * 부르는 쪽이 값을 주면 **그 흐름을 잇는다**(`trace-id` 를 유지하고 구간만 새로 딴다). 안 주면 우리가
+ * 시작한 흐름이다.
+ *
+ * ── 모양이 이상하면 **잇지 않고 새로 시작한다** ────────────────────────────
+ * 남이 준 값을 검사 없이 실어 보내면 우리 로그에 남의 형식이 섞이고, 수집기가 그 줄을 통째로 버린다.
+ * 그러면 **추적을 붙였는데 아무것도 안 이어지는** 상태가 된다 — 안 붙인 것보다 나쁘다.
+ *
+ * 전부 0인 값도 규격이 금지한다(§3.2.2.3). 그것을 이으면 서로 다른 흐름이 한 덩어리가 된다.
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRACEPARENT = void 0;
+exports.parseTraceparent = parseTraceparent;
+exports.traceFor = traceFor;
+exports.toTraceparent = toTraceparent;
+exports.traceTag = traceTag;
+/** W3C 가 정한 헤더 이름. 소문자다. */
+exports.TRACEPARENT = 'traceparent';
+/** 우리가 내는 버전. Level 1 은 `00` 하나뿐이다. */
+const VERSION = '00';
+/** 표본으로 남긴다 — 우리는 모두 남기므로 늘 켜 둔다. */
+const SAMPLED = '01';
+const TRACEPARENT_SHAPE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+/**
+ * 받은 헤더에서 **이을 수 있는 흐름**만 꺼낸다.
+ *
+ * 못 이으면 `undefined` — 부르는 쪽이 그때 새로 시작한다. **고쳐서 쓰지 않는다**(머리말).
+ */
+function parseTraceparent(header) {
+    if (typeof header !== 'string') {
+        return undefined;
+    }
+    const matched = TRACEPARENT_SHAPE.exec(header.trim().toLowerCase());
+    if (!matched) {
+        return undefined;
+    }
+    const [, version, traceId, spanId] = matched;
+    /* `ff` 는 규격이 잘못된 값으로 정한다(§3.2.2.1). 뒤 버전은 앞부분이 같으므로 읽어도 된다. */
+    if (version === 'ff') {
+        return undefined;
+    }
+    /* 전부 0인 식별자는 규격이 금지한다 — 이으면 서로 다른 흐름이 한 덩어리가 된다. */
+    if (/^0+$/.test(traceId) || /^0+$/.test(spanId)) {
+        return undefined;
+    }
+    return { traceId, spanId };
+}
+/**
+ * 이 구간의 추적 값을 만든다.
+ *
+ * `incoming` 이 이을 수 있으면 그 흐름을 잇고, 아니면 새로 시작한다.
+ */
+function traceFor(incoming, random = hex) {
+    const found = parseTraceparent(incoming);
+    return {
+        /* **자리 수를 늘 맞춘다.** 짧으면 규격에 안 맞아 받는 쪽이 헤더를 통째로 버린다 — 붙였는데
+           아무것도 안 이어지는 상태가 되고, 그건 안 붙인 것보다 나쁘다. */
+        traceId: found ? found.traceId : fit(random(), 32),
+        spanId: fit(random(), 16),
+        continued: !!found
+    };
+}
+/** 16진수를 정확히 그 자리 수로. 모자라면 채우고 남으면 자른다. */
+function fit(value, size) {
+    return value.padEnd(size, '0').slice(0, size);
+}
+/** 내보낼 헤더 값. 받는 쪽이 이것을 이어 간다. */
+function toTraceparent(trace) {
+    return `${VERSION}-${trace.traceId}-${trace.spanId}-${SAMPLED}`;
+}
+/**
+ * 로그에 붙일 짧은 표시.
+ *
+ * 32자리를 매 줄에 적으면 사람이 안 읽는다. 앞 8자리면 한 서버의 하루 안에서 충분히 갈린다 —
+ * **대조용이지 식별자가 아니다.** 정확히 이을 때는 전체 값을 쓴다.
+ */
+function traceTag(trace) {
+    return trace.traceId.slice(0, 8);
+}
+/** 16진수 32자리. 시각을 앞에 두어 같은 밀리초가 아니면 앞자리부터 갈린다. */
+function hex() {
+    const now = Date.now().toString(16).padStart(12, '0');
+    const tail = Array.from({ length: 5 }, () => Math.floor(Math.random() * 0xffff).toString(16).padStart(4, '0')).join('');
+    return (now + tail).slice(0, 32);
+}
+//# sourceMappingURL=trace-context.js.map

package/dist-server/service/observability/trace-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-context.js","sourceRoot":"","sources":["../../../server/service/observability/trace-context.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;;AA2BH,4CAuBC;AAOD,4BAUC;AAQD,sCAEC;AAQD,4BAEC;AArFD,4BAA4B;AACf,QAAA,WAAW,GAAG,aAAa,CAAA;AAExC,uCAAuC;AACvC,MAAM,OAAO,GAAG,IAAI,CAAA;AAEpB,qCAAqC;AACrC,MAAM,OAAO,GAAG,IAAI,CAAA;AAWpB,MAAM,iBAAiB,GAAG,6DAA6D,CAAA;AAEvF;;;;GAIG;AACH,SAAgB,gBAAgB,CAAC,MAAe;IAC9C,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAA;IACnE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,OAAO,CAAA;IAE5C,+DAA+D;IAC/D,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,oDAAoD;IACpD,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAChD,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAA;AAC5B,CAAC;AAED;;;;GAIG;AACH,SAAgB,QAAQ,CAAC,QAAiB,EAAE,SAAuB,GAAG;IACpE,MAAM,KAAK,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAA;IAExC,OAAO;QACL;kDAC0C;QAC1C,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC;QAClD,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC;QACzB,SAAS,EAAE,CAAC,CAAC,KAAK;KACnB,CAAA;AACH,CAAC;AAED,2CAA2C;AAC3C,SAAS,GAAG,CAAC,KAAa,EAAE,IAAY;IACtC,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;AAC/C,CAAC;AAED,iCAAiC;AACjC,SAAgB,aAAa,CAAC,KAAmB;IAC/C,OAAO,GAAG,OAAO,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,MAAM,IAAI,OAAO,EAAE,CAAA;AACjE,CAAC;AAED;;;;;GAKG;AACH,SAAgB,QAAQ,CAAC,KAAmB;IAC1C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AAClC,CAAC;AAED,kDAAkD;AAClD,SAAS,GAAG;IACV,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAA;IACrD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAEvH,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;AAClC,CAAC","sourcesContent":["/**\n * **한 사실이 어디를 지났는지 잇는 값** — W3C Trace Context 의 `traceparent`.\n *\n * ═══════════════════════════════════════════════════════════════════════════\n * ── 무엇이 없어서 무엇이 아팠나 ────────────────────────────────────────────\n * 실적 하나가 MES 에서 트윈까지 가는 데 다섯 봉투가 나간다. 그중 하나가 안 앉으면 **양쪽 로그를\n * 사람이 눈으로 맞춰야 한다.**\n *\n * 실제로 그랬다(2026-09-05). 봉투가 저널에 앉았는지 확인하려고 두 사람이 `seq` 와 밀리초 시각으로\n * 대조했고, 한 건이 조용히 합쳐진 것을 찾는 데 그 대조가 전부였다. 잇는 값이 있었으면 한 번에 찾았다.\n *\n * ── 왜 우리 것을 짓지 않나 ─────────────────────────────────────────────────\n * W3C 가 이미 정했고(Trace Context Level 1), 모든 수집기가 그 이름으로 읽는다. 우리 이름으로 지으면\n * 우리 로그에서만 이어지고 그 밖에서는 아무 뜻이 없다.\n *\n * ```\n * traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01\n *              ^^ ^──────── trace-id ────────────^ ^─ parent-id ─^ ^^ flags\n *              버전         한 흐름 전체를 가리킨다   이 구간         샘플 여부\n * ```\n *\n * ── 받은 것을 이어 간다. 없으면 시작한다 ───────────────────────────────────\n * 부르는 쪽이 값을 주면 **그 흐름을 잇는다**(`trace-id` 를 유지하고 구간만 새로 딴다). 안 주면 우리가\n * 시작한 흐름이다.\n *\n * ── 모양이 이상하면 **잇지 않고 새로 시작한다** ────────────────────────────\n * 남이 준 값을 검사 없이 실어 보내면 우리 로그에 남의 형식이 섞이고, 수집기가 그 줄을 통째로 버린다.\n * 그러면 **추적을 붙였는데 아무것도 안 이어지는** 상태가 된다 — 안 붙인 것보다 나쁘다.\n *\n * 전부 0인 값도 규격이 금지한다(§3.2.2.3). 그것을 이으면 서로 다른 흐름이 한 덩어리가 된다.\n * ═══════════════════════════════════════════════════════════════════════════\n */\n\n/** W3C 가 정한 헤더 이름. 소문자다. */\nexport const TRACEPARENT = 'traceparent'\n\n/** 우리가 내는 버전. Level 1 은 `00` 하나뿐이다. */\nconst VERSION = '00'\n\n/** 표본으로 남긴다 — 우리는 모두 남기므로 늘 켜 둔다. */\nconst SAMPLED = '01'\n\nexport interface TraceContext {\n  /** 한 흐름 전체 — 32자리 16진수. 실적 하나가 트윈까지 가는 동안 같은 값이다. */\n  traceId: string\n  /** 이 구간 — 16자리 16진수. 봉투마다 새로 딴다. */\n  spanId: string\n  /** 부르는 쪽이 준 값을 이었나. 거짓이면 우리가 시작한 흐름이다. */\n  continued: boolean\n}\n\nconst TRACEPARENT_SHAPE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/\n\n/**\n * 받은 헤더에서 **이을 수 있는 흐름**만 꺼낸다.\n *\n * 못 이으면 `undefined` — 부르는 쪽이 그때 새로 시작한다. **고쳐서 쓰지 않는다**(머리말).\n */\nexport function parseTraceparent(header: unknown): { traceId: string; spanId: string } | undefined {\n  if (typeof header !== 'string') {\n    return undefined\n  }\n\n  const matched = TRACEPARENT_SHAPE.exec(header.trim().toLowerCase())\n  if (!matched) {\n    return undefined\n  }\n\n  const [, version, traceId, spanId] = matched\n\n  /* `ff` 는 규격이 잘못된 값으로 정한다(§3.2.2.1). 뒤 버전은 앞부분이 같으므로 읽어도 된다. */\n  if (version === 'ff') {\n    return undefined\n  }\n\n  /* 전부 0인 식별자는 규격이 금지한다 — 이으면 서로 다른 흐름이 한 덩어리가 된다. */\n  if (/^0+$/.test(traceId) || /^0+$/.test(spanId)) {\n    return undefined\n  }\n\n  return { traceId, spanId }\n}\n\n/**\n * 이 구간의 추적 값을 만든다.\n *\n * `incoming` 이 이을 수 있으면 그 흐름을 잇고, 아니면 새로 시작한다.\n */\nexport function traceFor(incoming: unknown, random: () => string = hex): TraceContext {\n  const found = parseTraceparent(incoming)\n\n  return {\n    /* **자리 수를 늘 맞춘다.** 짧으면 규격에 안 맞아 받는 쪽이 헤더를 통째로 버린다 — 붙였는데\n       아무것도 안 이어지는 상태가 되고, 그건 안 붙인 것보다 나쁘다. */\n    traceId: found ? found.traceId : fit(random(), 32),\n    spanId: fit(random(), 16),\n    continued: !!found\n  }\n}\n\n/** 16진수를 정확히 그 자리 수로. 모자라면 채우고 남으면 자른다. */\nfunction fit(value: string, size: number): string {\n  return value.padEnd(size, '0').slice(0, size)\n}\n\n/** 내보낼 헤더 값. 받는 쪽이 이것을 이어 간다. */\nexport function toTraceparent(trace: TraceContext): string {\n  return `${VERSION}-${trace.traceId}-${trace.spanId}-${SAMPLED}`\n}\n\n/**\n * 로그에 붙일 짧은 표시.\n *\n * 32자리를 매 줄에 적으면 사람이 안 읽는다. 앞 8자리면 한 서버의 하루 안에서 충분히 갈린다 —\n * **대조용이지 식별자가 아니다.** 정확히 이을 때는 전체 값을 쓴다.\n */\nexport function traceTag(trace: TraceContext): string {\n  return trace.traceId.slice(0, 8)\n}\n\n/** 16진수 32자리. 시각을 앞에 두어 같은 밀리초가 아니면 앞자리부터 갈린다. */\nfunction hex(): string {\n  const now = Date.now().toString(16).padStart(12, '0')\n  const tail = Array.from({ length: 5 }, () => Math.floor(Math.random() * 0xffff).toString(16).padStart(4, '0')).join('')\n\n  return (now + tail).slice(0, 32)\n}\n"]}

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

@@ -0,0 +1,85 @@
+import { type MaybeTransactional } from './writing-transaction.js';
+/**
+ * **The back row of the outbox** — writing a fact down so it can be delivered later
+ * (ADR-0078 decision 2 ②).
+ *
+ * ═════════════════════════════════════════════════════════════════════════
+ * ## The number can burn, and nothing says so
+ *
+ * A number is taken by raising a counter, and the row is written with it. If those two are not in one
+ * transaction, the raise commits on its own and a later failure leaves a number that names no row.
+ * The receiver stops at that hole and waits for a record that will never come.
+ *
+ * It happened: 200 numbers in one stretch (968..1167) at one site, found months later by counting rows
+ * against numbers. There is no delete anywhere in this machine, so the rows were not removed - the
+ * numbers were burned. A caller had passed the default manager, where every statement commits where it
+ * stands.
+ *
+ * ## So the transaction is in the type, not only in a check
+ *
+ * `OpenTransaction` cannot be written down by hand: the only way to get one is through
+ * `openTransaction(manager)`, which throws when the manager is not in a transaction. A plain manager
+ * does not compile here. The runtime check stays for callers who reach this through JavaScript.
+ *
+ * ## The store does not know what a row is made of
+ *
+ * Allocating and inserting belong to whoever owns the table (this module over its own, operato-plant
+ * over its own until those rows move). What belongs here is the order of the two, the grouping by
+ * stream, and the refusals below - which is what makes the machine one machine rather than two copies.
+ * ═════════════════════════════════════════════════════════════════════════
+ */
+declare const OPEN_TRANSACTION: unique symbol;
+/**
+ * A manager that is **in an open transaction**. Obtained only from `openTransaction`, so a function
+ * asking for one cannot be handed the default manager by mistake.
+ */
+export type OpenTransaction<T = unknown> = T & {
+    readonly [OPEN_TRANSACTION]: true;
+};
+/** Throws when this manager is not in a transaction; otherwise hands it back as one. */
+export declare function openTransaction<T extends MaybeTransactional>(manager: T): OpenTransaction<T>;
+/** What is written down about one fact. The record itself is opaque here. */
+export interface OutboxAppendInput<Fact = unknown> {
+    /** The fact, as the contract shapes it. */
+    record: Fact;
+    /** The receiver's own id for this envelope. One is made when the caller does not name it. */
+    eventId?: string;
+    /** When it happened. Defaults to when it was recorded. */
+    eventTime?: Date;
+    /** Anything else this product keeps per row - lane, provenance, and the like. */
+    extra?: Record<string, unknown>;
+}
+/** A row on its way into the table, before the store gives it an id. */
+export interface NewOutboxRow<Fact = unknown> {
+    seq: number;
+    eventId: string;
+    eventTime: Date;
+    recordTime: Date;
+    record: Fact;
+    extra?: Record<string, unknown>;
+}
+/**
+ * The half of a store that writes. Bound to one stream, like the reading half.
+ *
+ * `allocate` raises this stream's counter by `count` and answers the **first** number of the run it
+ * just took. Raising and answering are one step on purpose: two callers that read, add and write would
+ * hand out the same number.
+ */
+export interface OutboxAppendStore<Fact = unknown, Row = unknown> {
+    allocate(count: number): Promise<number>;
+    insert(rows: readonly NewOutboxRow<Fact>[]): Promise<Row[]>;
+}
+/** What a record has to satisfy before it is written down. The caller declares this per product. */
+export type RecordCheck<Fact = unknown> = (record: Fact) => string[];
+/**
+ * Write these facts down, in one run of numbers, inside the caller's transaction.
+ *
+ * Refusals are here rather than at the receiver because this runs **inside the business transaction**:
+ * refusing rolls the work back, so a fact with a broken identity is never recorded in the first place.
+ * Let it through and it lands in the receiver's dead letters, by which time the fact is late and the
+ * row that caused it is already committed.
+ */
+export declare function appendOutbox<Fact, Row>(tx: OpenTransaction, store: OutboxAppendStore<Fact, Row>, inputs: readonly OutboxAppendInput<Fact>[], options?: {
+    check?: RecordCheck<Fact>;
+}): Promise<Row[]>;
+export {};

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

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openTransaction = openTransaction;
+exports.appendOutbox = appendOutbox;
+const crypto_1 = require("crypto");
+const writing_transaction_js_1 = require("./writing-transaction.js");
+/** Throws when this manager is not in a transaction; otherwise hands it back as one. */
+function openTransaction(manager) {
+    (0, writing_transaction_js_1.assertWritingTransaction)(manager);
+    return manager;
+}
+/**
+ * Write these facts down, in one run of numbers, inside the caller's transaction.
+ *
+ * Refusals are here rather than at the receiver because this runs **inside the business transaction**:
+ * refusing rolls the work back, so a fact with a broken identity is never recorded in the first place.
+ * Let it through and it lands in the receiver's dead letters, by which time the fact is late and the
+ * row that caused it is already committed.
+ */
+async function appendOutbox(tx, store, inputs, options = {}) {
+    if (!inputs?.length) {
+        return [];
+    }
+    for (const input of inputs) {
+        if (!input.record || typeof input.record !== 'object') {
+            throw new Error('appendOutbox: record is required - an empty payload would be delivered as a fact');
+        }
+        const violations = options.check?.(input.record) ?? [];
+        if (violations.length) {
+            throw new Error(`appendOutbox: identity is not valid - ${violations.join(' · ')}`);
+        }
+    }
+    /* The type says this already; the check stays for callers arriving from JavaScript. */
+    (0, writing_transaction_js_1.assertWritingTransaction)(tx);
+    const recordTime = new Date();
+    const firstSeq = await store.allocate(inputs.length);
+    return await store.insert(inputs.map((input, index) => ({
+        seq: firstSeq + index,
+        eventId: input.eventId ?? `urn:uuid:${(0, crypto_1.randomUUID)()}`,
+        eventTime: input.eventTime ?? recordTime,
+        recordTime,
+        record: input.record,
+        ...(input.extra ? { extra: input.extra } : {})
+    })));
+}
+//# sourceMappingURL=append.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"append.js","sourceRoot":"","sources":["../../../server/service/outbox/append.ts"],"names":[],"mappings":";;AA2CA,0CAIC;AA+CD,oCAsCC;AApID,mCAAmC;AAEnC,qEAA4F;AAwC5F,wFAAwF;AACxF,SAAgB,eAAe,CAA+B,OAAU;IACtE,IAAA,iDAAwB,EAAC,OAAO,CAAC,CAAA;IAEjC,OAAO,OAA6B,CAAA;AACtC,CAAC;AAuCD;;;;;;;GAOG;AACI,KAAK,UAAU,YAAY,CAChC,EAAmB,EACnB,KAAmC,EACnC,MAA0C,EAC1C,UAAyC,EAAE;IAE3C,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QACpB,OAAO,EAAE,CAAA;IACX,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CAAC,kFAAkF,CAAC,CAAA;QACrG,CAAC;QAED,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAA;QAEtD,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,yCAAyC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QACpF,CAAC;IACH,CAAC;IAED,uFAAuF;IACvF,IAAA,iDAAwB,EAAC,EAAwB,CAAC,CAAA;IAElD,MAAM,UAAU,GAAG,IAAI,IAAI,EAAE,CAAA;IAC7B,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAEpD,OAAO,MAAM,KAAK,CAAC,MAAM,CACvB,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QAC5B,GAAG,EAAE,QAAQ,GAAG,KAAK;QACrB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,YAAY,IAAA,mBAAU,GAAE,EAAE;QACpD,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,UAAU;QACxC,UAAU;QACV,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/C,CAAC,CAAC,CACJ,CAAA;AACH,CAAC","sourcesContent":["import { randomUUID } from 'crypto'\n\nimport { assertWritingTransaction, type MaybeTransactional } from './writing-transaction.js'\n\n/**\n * **The back row of the outbox** — writing a fact down so it can be delivered later\n * (ADR-0078 decision 2 ②).\n *\n * ═════════════════════════════════════════════════════════════════════════\n * ## The number can burn, and nothing says so\n *\n * A number is taken by raising a counter, and the row is written with it. If those two are not in one\n * transaction, the raise commits on its own and a later failure leaves a number that names no row.\n * The receiver stops at that hole and waits for a record that will never come.\n *\n * It happened: 200 numbers in one stretch (968..1167) at one site, found months later by counting rows\n * against numbers. There is no delete anywhere in this machine, so the rows were not removed - the\n * numbers were burned. A caller had passed the default manager, where every statement commits where it\n * stands.\n *\n * ## So the transaction is in the type, not only in a check\n *\n * `OpenTransaction` cannot be written down by hand: the only way to get one is through\n * `openTransaction(manager)`, which throws when the manager is not in a transaction. A plain manager\n * does not compile here. The runtime check stays for callers who reach this through JavaScript.\n *\n * ## The store does not know what a row is made of\n *\n * Allocating and inserting belong to whoever owns the table (this module over its own, operato-plant\n * over its own until those rows move). What belongs here is the order of the two, the grouping by\n * stream, and the refusals below - which is what makes the machine one machine rather than two copies.\n * ═════════════════════════════════════════════════════════════════════════\n */\n\ndeclare const OPEN_TRANSACTION: unique symbol\n\n/**\n * A manager that is **in an open transaction**. Obtained only from `openTransaction`, so a function\n * asking for one cannot be handed the default manager by mistake.\n */\nexport type OpenTransaction<T = unknown> = T & { readonly [OPEN_TRANSACTION]: true }\n\n/** Throws when this manager is not in a transaction; otherwise hands it back as one. */\nexport function openTransaction<T extends MaybeTransactional>(manager: T): OpenTransaction<T> {\n  assertWritingTransaction(manager)\n\n  return manager as OpenTransaction<T>\n}\n\n/** What is written down about one fact. The record itself is opaque here. */\nexport interface OutboxAppendInput<Fact = unknown> {\n  /** The fact, as the contract shapes it. */\n  record: Fact\n  /** The receiver's own id for this envelope. One is made when the caller does not name it. */\n  eventId?: string\n  /** When it happened. Defaults to when it was recorded. */\n  eventTime?: Date\n  /** Anything else this product keeps per row - lane, provenance, and the like. */\n  extra?: Record<string, unknown>\n}\n\n/** A row on its way into the table, before the store gives it an id. */\nexport interface NewOutboxRow<Fact = unknown> {\n  seq: number\n  eventId: string\n  eventTime: Date\n  recordTime: Date\n  record: Fact\n  extra?: Record<string, unknown>\n}\n\n/**\n * The half of a store that writes. Bound to one stream, like the reading half.\n *\n * `allocate` raises this stream's counter by `count` and answers the **first** number of the run it\n * just took. Raising and answering are one step on purpose: two callers that read, add and write would\n * hand out the same number.\n */\nexport interface OutboxAppendStore<Fact = unknown, Row = unknown> {\n  allocate(count: number): Promise<number>\n  insert(rows: readonly NewOutboxRow<Fact>[]): Promise<Row[]>\n}\n\n/** What a record has to satisfy before it is written down. The caller declares this per product. */\nexport type RecordCheck<Fact = unknown> = (record: Fact) => string[]\n\n/**\n * Write these facts down, in one run of numbers, inside the caller's transaction.\n *\n * Refusals are here rather than at the receiver because this runs **inside the business transaction**:\n * refusing rolls the work back, so a fact with a broken identity is never recorded in the first place.\n * Let it through and it lands in the receiver's dead letters, by which time the fact is late and the\n * row that caused it is already committed.\n */\nexport async function appendOutbox<Fact, Row>(\n  tx: OpenTransaction,\n  store: OutboxAppendStore<Fact, Row>,\n  inputs: readonly OutboxAppendInput<Fact>[],\n  options: { check?: RecordCheck<Fact> } = {}\n): Promise<Row[]> {\n  if (!inputs?.length) {\n    return []\n  }\n\n  for (const input of inputs) {\n    if (!input.record || typeof input.record !== 'object') {\n      throw new Error('appendOutbox: record is required - an empty payload would be delivered as a fact')\n    }\n\n    const violations = options.check?.(input.record) ?? []\n\n    if (violations.length) {\n      throw new Error(`appendOutbox: identity is not valid - ${violations.join(' · ')}`)\n    }\n  }\n\n  /* The type says this already; the check stays for callers arriving from JavaScript. */\n  assertWritingTransaction(tx as MaybeTransactional)\n\n  const recordTime = new Date()\n  const firstSeq = await store.allocate(inputs.length)\n\n  return await store.insert(\n    inputs.map((input, index) => ({\n      seq: firstSeq + index,\n      eventId: input.eventId ?? `urn:uuid:${randomUUID()}`,\n      eventTime: input.eventTime ?? recordTime,\n      recordTime,\n      record: input.record,\n      ...(input.extra ? { extra: input.extra } : {})\n    }))\n  )\n}\n"]}