@things-factory/webhook 10.1.37 → 10.1.38

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

@@ -1,7 +1,15 @@
+import { WebhookDestination } from './webhook-destination/webhook-destination';
+import { WebhookDestinationResolver } from './webhook-destination/webhook-destination-resolver';
+import { WebhookOutboxEvent } from './webhook-outbox-event/webhook-outbox-event';
+import { WebhookSequence } from './webhook-sequence/webhook-sequence';
 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 declare const entities: (typeof WebhookDestination | typeof WebhookOutboxEvent | typeof WebhookSequence)[];
+export declare const schema: {
+    resolverClasses: (typeof WebhookDestinationResolver)[];
+};
 export * from './outbox/delivery';
 export * from './outbox/settlement';
 export * from './outbox/row-effect';
@@ -18,3 +26,4 @@ export * from './observability/trace-context';
 export * from './outbox/store';
 export * from './outbox/dispatcher';
 export * from './outbox/webhook-store';
+export * from './outbox/webhook-append-store';

package/dist-server/service/index.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.schema = exports.entities = void 0;
 const tslib_1 = require("tslib");
 /*
  * Each source file is named rather than re-exporting folder barrels.
@@ -10,10 +11,22 @@ const tslib_1 = require("tslib");
  * `work-shift/days-of-week`: the parser was in the folder barrel, not here, and the consuming
  * lane wrote its own until the miss was found.
  */
+const webhook_destination_1 = require("./webhook-destination/webhook-destination");
+const webhook_destination_resolver_1 = require("./webhook-destination/webhook-destination-resolver");
+const webhook_outbox_event_1 = require("./webhook-outbox-event/webhook-outbox-event");
+const webhook_sequence_1 = require("./webhook-sequence/webhook-sequence");
 tslib_1.__exportStar(require("./webhook-destination/webhook-destination"), exports);
 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 shell builds the database and the schema from these two names.** Without them the module's
+ * tables are never created in any application and the destination door is in no schema - the files stand
+ * and nothing reaches them. That was the state through 10.1.37 (found 2026-09-24 by the first application to
+ * append: its database had no webhook table at all). `test/append-store-db.test.ts` holds this line.
+ */
+exports.entities = [webhook_destination_1.WebhookDestination, webhook_outbox_event_1.WebhookOutboxEvent, webhook_sequence_1.WebhookSequence];
+exports.schema = { resolverClasses: [webhook_destination_resolver_1.WebhookDestinationResolver] };
 /*
  * 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,
@@ -42,4 +55,5 @@ tslib_1.__exportStar(require("./observability/trace-context"), exports);
 tslib_1.__exportStar(require("./outbox/store"), exports);
 tslib_1.__exportStar(require("./outbox/dispatcher"), exports);
 tslib_1.__exportStar(require("./outbox/webhook-store"), exports);
+tslib_1.__exportStar(require("./outbox/webhook-append-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;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"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../server/service/index.ts"],"names":[],"mappings":";;;;AAAA;;;;;;;;GAQG;AACH,mFAA8E;AAC9E,qGAA+F;AAC/F,sFAAgF;AAChF,0EAAqE;AAErE,oFAAyD;AACzD,6FAAkE;AAClE,sFAA2D;AAC3D,8EAAmD;AAEnD;;;;;GAKG;AACU,QAAA,QAAQ,GAAG,CAAC,wCAAkB,EAAE,yCAAkB,EAAE,kCAAe,CAAC,CAAA;AAEpE,QAAA,MAAM,GAAG,EAAE,eAAe,EAAE,CAAC,yDAA0B,CAAC,EAAE,CAAA;AAEvE;;;;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;AACtC,wEAA6C","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 */\nimport { WebhookDestination } from './webhook-destination/webhook-destination'\nimport { WebhookDestinationResolver } from './webhook-destination/webhook-destination-resolver'\nimport { WebhookOutboxEvent } from './webhook-outbox-event/webhook-outbox-event'\nimport { WebhookSequence } from './webhook-sequence/webhook-sequence'\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 shell builds the database and the schema from these two names.** Without them the module's\n * tables are never created in any application and the destination door is in no schema - the files stand\n * and nothing reaches them. That was the state through 10.1.37 (found 2026-09-24 by the first application to\n * append: its database had no webhook table at all). `test/append-store-db.test.ts` holds this line.\n */\nexport const entities = [WebhookDestination, WebhookOutboxEvent, WebhookSequence]\n\nexport const schema = { resolverClasses: [WebhookDestinationResolver] }\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'\nexport * from './outbox/webhook-append-store'\n\n"]}

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

@@ -0,0 +1,63 @@
+/**
+ * **What one round of the pump does with each stream** — a pure judgement: no database, no network, and
+ * the environment arrives as an argument (ADR-0078 decision 5 as re-ruled on 2026-09-24).
+ *
+ * ═════════════════════════════════════════════════════════════════════════
+ * ## Silence is the failure this guards
+ *
+ * Facts can pile up for three reasons, and none of them fails anything: no destination is declared for
+ * that peer, a person turned the destination off, or nothing can sign. Each sends the administrator
+ * somewhere different - declare it, turn it back on, set a key - so each is its own sentence, and each
+ * comes with a key the pump says it once by. Said every round, the line buries everything else.
+ *
+ * ## The key's name belongs to the contract
+ *
+ * `webhookSecretFrom` walks the contract's ladder - per peer, then per domain - and a product passes no
+ * names of its own. Pinned to the peer, two products on one installation never share a key. A product that
+ * ran before this ladder passes `legacyBases`; a key found there is used and said once, because a quiet
+ * success means nobody ever moves to the new name.
+ *
+ * The missing-key sentence names the variables. That is for the process log only - the contract says so
+ * (`webhookSecretMissingNote`) - and this sentence never goes into a response.
+ * ═════════════════════════════════════════════════════════════════════════
+ */
+/** One stream with facts waiting. The pump reads these off the pending rows. */
+export interface PendingStream {
+    domainId: string;
+    /** The tenant's name - what the key's name is built from and what a person reads in the log. */
+    subdomain: string;
+    peer: string;
+    scope: string;
+}
+/** What the destination row says, read by the caller. */
+export interface DestinationReading {
+    endpoint: string;
+    active: boolean;
+    params?: {
+        receivingDomain?: string;
+    } & Record<string, unknown>;
+}
+export interface RoundNote {
+    /** The same cause on the same stream carries the same key, so it is said once. */
+    key: string;
+    line: string;
+}
+export type RoundStep = {
+    kind: 'deliver';
+    stream: PendingStream;
+    endpoint: string;
+    secret: string;
+    headers: Record<string, string>;
+    /** Clock readings are kept per peer - two peers' clocks are not one clock. */
+    clockKey: string;
+    note?: RoundNote;
+} | {
+    kind: 'wait';
+    stream: PendingStream;
+    note: RoundNote;
+};
+export interface RoundOptions {
+    /** Names this product's installations used before the ladder. Absent for a product that never had one. */
+    legacyBases?: readonly string[];
+}
+export declare function planRound(streams: readonly PendingStream[], destinationOf: (domainId: string, peer: string) => DestinationReading | undefined, env: Record<string, string | undefined>, options?: RoundOptions): RoundStep[];

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

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planRound = planRound;
+const ops_contract_1 = require("@operato/ops-contract");
+function planRound(streams, destinationOf, env, options = {}) {
+    return streams.map(stream => planStream(stream, destinationOf(stream.domainId, stream.peer), env, options));
+}
+function planStream(stream, destination, env, options) {
+    const { subdomain, peer } = stream;
+    const where = `"${subdomain}" → ${peer}`;
+    if (!destination?.endpoint) {
+        return {
+            kind: 'wait',
+            stream,
+            note: {
+                key: `no-destination:${subdomain}:${peer}`,
+                line: `[webhook] facts are piling up for ${where} but no destination is declared for that peer - set it on the webhook destinations screen. Nothing is lost.`
+            }
+        };
+    }
+    if (!destination.active) {
+        return {
+            kind: 'wait',
+            stream,
+            note: {
+                key: `turned-off:${subdomain}:${peer}`,
+                line: `[webhook] facts are piling up for ${where} - its destination is turned off. Nothing is lost; turn it back on when the receiver is ready.`
+            }
+        };
+    }
+    const lookup = { purpose: 'signing', domain: subdomain, peer, ...(options.legacyBases?.length ? { legacyBases: options.legacyBases } : {}) };
+    const found = (0, ops_contract_1.webhookSecretFrom)(env, lookup);
+    /*
+     * The answer is a union. This package compiles without `strictNullChecks`, and there a check on `secret`
+     * does not narrow it - so ask which branch it is by the field only that branch has.
+     */
+    if (!('opened' in found)) {
+        return {
+            kind: 'wait',
+            stream,
+            note: {
+                key: `no-secret:${subdomain}:${peer}`,
+                line: `[webhook] facts are piling up for ${where} but nothing can sign them - ${(0, ops_contract_1.webhookSecretMissingNote)(found.tried)} Nothing is lost; they go as soon as a key is there.`
+            }
+        };
+    }
+    const { secret, opened } = found;
+    const receivingDomain = destination.params?.receivingDomain;
+    return {
+        kind: 'deliver',
+        stream,
+        endpoint: destination.endpoint,
+        secret,
+        /* The receiver's own tenant - never assumed to be ours. */
+        headers: typeof receivingDomain === 'string' && receivingDomain ? { 'x-things-factory-domain': receivingDomain } : {},
+        clockKey: `${subdomain}:${peer}`,
+        ...(opened.compatibility
+            ? {
+                note: {
+                    key: `legacy-secret:${subdomain}:${peer}`,
+                    line: `[webhook] ${where} is signed with ${opened.name}, a name kept for installations that ran before - move the key to ${(0, ops_contract_1.webhookSecretCandidates)({ purpose: 'signing', domain: subdomain, peer })[0].name}.`
+                }
+            }
+            : {})
+    };
+}
+//# sourceMappingURL=pump-round.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pump-round.js","sourceRoot":"","sources":["../../../server/service/outbox/pump-round.ts"],"names":[],"mappings":"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","sourcesContent":["import { webhookSecretCandidates, webhookSecretFrom, webhookSecretMissingNote } from '@operato/ops-contract'\n\n/**\n * **What one round of the pump does with each stream** — a pure judgement: no database, no network, and\n * the environment arrives as an argument (ADR-0078 decision 5 as re-ruled on 2026-09-24).\n *\n * ═════════════════════════════════════════════════════════════════════════\n * ## Silence is the failure this guards\n *\n * Facts can pile up for three reasons, and none of them fails anything: no destination is declared for\n * that peer, a person turned the destination off, or nothing can sign. Each sends the administrator\n * somewhere different - declare it, turn it back on, set a key - so each is its own sentence, and each\n * comes with a key the pump says it once by. Said every round, the line buries everything else.\n *\n * ## The key's name belongs to the contract\n *\n * `webhookSecretFrom` walks the contract's ladder - per peer, then per domain - and a product passes no\n * names of its own. Pinned to the peer, two products on one installation never share a key. A product that\n * ran before this ladder passes `legacyBases`; a key found there is used and said once, because a quiet\n * success means nobody ever moves to the new name.\n *\n * The missing-key sentence names the variables. That is for the process log only - the contract says so\n * (`webhookSecretMissingNote`) - and this sentence never goes into a response.\n * ═════════════════════════════════════════════════════════════════════════\n */\n\n/** One stream with facts waiting. The pump reads these off the pending rows. */\nexport interface PendingStream {\n  domainId: string\n  /** The tenant's name - what the key's name is built from and what a person reads in the log. */\n  subdomain: string\n  peer: string\n  scope: string\n}\n\n/** What the destination row says, read by the caller. */\nexport interface DestinationReading {\n  endpoint: string\n  active: boolean\n  params?: { receivingDomain?: string } & Record<string, unknown>\n}\n\nexport interface RoundNote {\n  /** The same cause on the same stream carries the same key, so it is said once. */\n  key: string\n  line: string\n}\n\nexport type RoundStep =\n  | {\n      kind: 'deliver'\n      stream: PendingStream\n      endpoint: string\n      secret: string\n      headers: Record<string, string>\n      /** Clock readings are kept per peer - two peers' clocks are not one clock. */\n      clockKey: string\n      note?: RoundNote\n    }\n  | { kind: 'wait'; stream: PendingStream; note: RoundNote }\n\nexport interface RoundOptions {\n  /** Names this product's installations used before the ladder. Absent for a product that never had one. */\n  legacyBases?: readonly string[]\n}\n\nexport function planRound(\n  streams: readonly PendingStream[],\n  destinationOf: (domainId: string, peer: string) => DestinationReading | undefined,\n  env: Record<string, string | undefined>,\n  options: RoundOptions = {}\n): RoundStep[] {\n  return streams.map(stream => planStream(stream, destinationOf(stream.domainId, stream.peer), env, options))\n}\n\nfunction planStream(stream: PendingStream, destination: DestinationReading | undefined, env: Record<string, string | undefined>, options: RoundOptions): RoundStep {\n  const { subdomain, peer } = stream\n  const where = `\"${subdomain}\" → ${peer}`\n\n  if (!destination?.endpoint) {\n    return {\n      kind: 'wait',\n      stream,\n      note: {\n        key: `no-destination:${subdomain}:${peer}`,\n        line: `[webhook] facts are piling up for ${where} but no destination is declared for that peer - set it on the webhook destinations screen. Nothing is lost.`\n      }\n    }\n  }\n\n  if (!destination.active) {\n    return {\n      kind: 'wait',\n      stream,\n      note: {\n        key: `turned-off:${subdomain}:${peer}`,\n        line: `[webhook] facts are piling up for ${where} - its destination is turned off. Nothing is lost; turn it back on when the receiver is ready.`\n      }\n    }\n  }\n\n  const lookup = { purpose: 'signing' as const, domain: subdomain, peer, ...(options.legacyBases?.length ? { legacyBases: options.legacyBases } : {}) }\n  const found = webhookSecretFrom(env, lookup)\n\n  /*\n   * The answer is a union. This package compiles without `strictNullChecks`, and there a check on `secret`\n   * does not narrow it - so ask which branch it is by the field only that branch has.\n   */\n  if (!('opened' in found)) {\n    return {\n      kind: 'wait',\n      stream,\n      note: {\n        key: `no-secret:${subdomain}:${peer}`,\n        line: `[webhook] facts are piling up for ${where} but nothing can sign them - ${webhookSecretMissingNote(found.tried)} Nothing is lost; they go as soon as a key is there.`\n      }\n    }\n  }\n\n  const { secret, opened } = found\n  const receivingDomain = destination.params?.receivingDomain\n\n  return {\n    kind: 'deliver',\n    stream,\n    endpoint: destination.endpoint,\n    secret,\n    /* The receiver's own tenant - never assumed to be ours. */\n    headers: typeof receivingDomain === 'string' && receivingDomain ? { 'x-things-factory-domain': receivingDomain } : {},\n    clockKey: `${subdomain}:${peer}`,\n    ...(opened.compatibility\n      ? {\n          note: {\n            key: `legacy-secret:${subdomain}:${peer}`,\n            line: `[webhook] ${where} is signed with ${opened.name}, a name kept for installations that ran before - move the key to ${webhookSecretCandidates({ purpose: 'signing', domain: subdomain, peer })[0].name}.`\n          }\n        }\n      : {})\n  }\n}\n"]}

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

@@ -0,0 +1,5 @@
+import { EntityManager } from 'typeorm';
+import { WebhookOutboxEvent } from '../webhook-outbox-event/webhook-outbox-event.js';
+import type { OpenTransaction, OutboxAppendStore } from './append.js';
+import type { WebhookStream } from './webhook-store.js';
+export declare function webhookAppendStore(tx: OpenTransaction<EntityManager>, stream: WebhookStream): OutboxAppendStore<object, WebhookOutboxEvent>;

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

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webhookAppendStore = webhookAppendStore;
+const webhook_outbox_event_js_1 = require("../webhook-outbox-event/webhook-outbox-event.js");
+const webhook_sequence_js_1 = require("../webhook-sequence/webhook-sequence.js");
+/**
+ * **The front row over this module's own tables** — the writing half of one stream `(domain, peer, scope)`
+ * (ADR-0078 decision 2 ②, decision 6).
+ *
+ * ═════════════════════════════════════════════════════════════════════════
+ * ## It takes the open transaction, not a manager
+ *
+ * `allocate` raises the counter and `insert` writes the rows. If the two are not one transaction, the raise
+ * commits on its own and a failed insert leaves a number that names no row - the receiver stops at that hole
+ * for good. `OpenTransaction` can only come from `openTransaction`, so the default manager does not compile
+ * here. `test/append-store-db.test.ts` breaks an insert after the raise and reads the counter back.
+ *
+ * ## Raise, then read
+ *
+ * `increment` takes the row lock, so two writers on the same stream queue behind each other; reading after
+ * raising means the run handed out belongs to this transaction. Reading first and writing `last + n` would
+ * hand two writers the same numbers.
+ *
+ * The first append on a stream creates the counter row. Two first appends racing on a brand-new stream
+ * meet at the unique index and one of the two business transactions fails whole - loud, and nothing burned.
+ *
+ * ## What the product keeps per row
+ *
+ * `lane` and `provenance` are columns (decision 3); a product passes them in `extra`. Anything else in
+ * `extra` is refused: a key with no column would be accepted, dropped, and reported as written.
+ * ═════════════════════════════════════════════════════════════════════════
+ */
+const EXTRA_COLUMNS = new Set(['lane', 'provenance']);
+function webhookAppendStore(tx, stream) {
+    const { domainId, peer, scope } = stream;
+    const where = { domain: { id: domainId }, peer, scope };
+    return {
+        async allocate(count) {
+            const exists = await tx.findOne(webhook_sequence_js_1.WebhookSequence, { where });
+            if (!exists) {
+                await tx.save(webhook_sequence_js_1.WebhookSequence, tx.create(webhook_sequence_js_1.WebhookSequence, { domain: { id: domainId }, peer, scope, lastSeq: 0 }));
+            }
+            await tx.increment(webhook_sequence_js_1.WebhookSequence, where, 'lastSeq', count);
+            const after = await tx.findOne(webhook_sequence_js_1.WebhookSequence, { where });
+            if (!after) {
+                throw new Error(`webhookAppendStore: the counter for ${peer}/${scope} disappeared while allocating`);
+            }
+            /* Some drivers hand an int column back as a string. Count in numbers. */
+            const lastSeq = Number(after.lastSeq);
+            if (!Number.isFinite(lastSeq)) {
+                throw new Error(`webhookAppendStore: the counter for ${peer}/${scope} is not a number: ${String(after.lastSeq)}`);
+            }
+            return lastSeq - count + 1;
+        },
+        async insert(rows) {
+            const entities = rows.map(row => {
+                const unknown = Object.keys(row.extra ?? {}).filter(key => !EXTRA_COLUMNS.has(key));
+                if (unknown.length) {
+                    throw new Error(`webhookAppendStore: no column for ${unknown.join(', ')} - it would be dropped and reported as written`);
+                }
+                return tx.create(webhook_outbox_event_js_1.WebhookOutboxEvent, {
+                    domain: { id: domainId },
+                    peer,
+                    scope,
+                    seq: row.seq,
+                    eventId: row.eventId,
+                    eventTime: row.eventTime,
+                    recordTime: row.recordTime,
+                    payload: row.record,
+                    status: webhook_outbox_event_js_1.WebhookOutboxStatus.Pending,
+                    ...(row.extra ?? {})
+                });
+            });
+            return await tx.save(webhook_outbox_event_js_1.WebhookOutboxEvent, entities);
+        }
+    };
+}
+//# sourceMappingURL=webhook-append-store.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-append-store.js","sourceRoot":"","sources":["../../../server/service/outbox/webhook-append-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { EntityManager } from 'typeorm'\n\nimport { WebhookOutboxEvent, WebhookOutboxStatus } from '../webhook-outbox-event/webhook-outbox-event.js'\nimport { WebhookSequence } from '../webhook-sequence/webhook-sequence.js'\nimport type { NewOutboxRow, OpenTransaction, OutboxAppendStore } from './append.js'\nimport type { WebhookStream } from './webhook-store.js'\n\n/**\n * **The front row over this module's own tables** — the writing half of one stream `(domain, peer, scope)`\n * (ADR-0078 decision 2 ②, decision 6).\n *\n * ═════════════════════════════════════════════════════════════════════════\n * ## It takes the open transaction, not a manager\n *\n * `allocate` raises the counter and `insert` writes the rows. If the two are not one transaction, the raise\n * commits on its own and a failed insert leaves a number that names no row - the receiver stops at that hole\n * for good. `OpenTransaction` can only come from `openTransaction`, so the default manager does not compile\n * here. `test/append-store-db.test.ts` breaks an insert after the raise and reads the counter back.\n *\n * ## Raise, then read\n *\n * `increment` takes the row lock, so two writers on the same stream queue behind each other; reading after\n * raising means the run handed out belongs to this transaction. Reading first and writing `last + n` would\n * hand two writers the same numbers.\n *\n * The first append on a stream creates the counter row. Two first appends racing on a brand-new stream\n * meet at the unique index and one of the two business transactions fails whole - loud, and nothing burned.\n *\n * ## What the product keeps per row\n *\n * `lane` and `provenance` are columns (decision 3); a product passes them in `extra`. Anything else in\n * `extra` is refused: a key with no column would be accepted, dropped, and reported as written.\n * ═════════════════════════════════════════════════════════════════════════\n */\n\nconst EXTRA_COLUMNS = new Set(['lane', 'provenance'])\n\nexport function webhookAppendStore(tx: OpenTransaction<EntityManager>, stream: WebhookStream): OutboxAppendStore<object, WebhookOutboxEvent> {\n  const { domainId, peer, scope } = stream\n  const where = { domain: { id: domainId }, peer, scope }\n\n  return {\n    async allocate(count: number): Promise<number> {\n      const exists = await tx.findOne(WebhookSequence, { where })\n\n      if (!exists) {\n        await tx.save(WebhookSequence, tx.create(WebhookSequence, { domain: { id: domainId } as any, peer, scope, lastSeq: 0 }))\n      }\n\n      await tx.increment(WebhookSequence, where, 'lastSeq', count)\n\n      const after = await tx.findOne(WebhookSequence, { where })\n      if (!after) {\n        throw new Error(`webhookAppendStore: the counter for ${peer}/${scope} disappeared while allocating`)\n      }\n\n      /* Some drivers hand an int column back as a string. Count in numbers. */\n      const lastSeq = Number(after.lastSeq)\n      if (!Number.isFinite(lastSeq)) {\n        throw new Error(`webhookAppendStore: the counter for ${peer}/${scope} is not a number: ${String(after.lastSeq)}`)\n      }\n\n      return lastSeq - count + 1\n    },\n\n    async insert(rows: readonly NewOutboxRow<object>[]): Promise<WebhookOutboxEvent[]> {\n      const entities = rows.map(row => {\n        const unknown = Object.keys(row.extra ?? {}).filter(key => !EXTRA_COLUMNS.has(key))\n        if (unknown.length) {\n          throw new Error(`webhookAppendStore: no column for ${unknown.join(', ')} - it would be dropped and reported as written`)\n        }\n\n        return tx.create(WebhookOutboxEvent, {\n          domain: { id: domainId } as any,\n          peer,\n          scope,\n          seq: row.seq,\n          eventId: row.eventId,\n          eventTime: row.eventTime,\n          recordTime: row.recordTime,\n          payload: row.record,\n          status: WebhookOutboxStatus.Pending,\n          ...(row.extra ?? {})\n        })\n      })\n\n      return await tx.save(WebhookOutboxEvent, entities)\n    }\n  }\n}\n"]}