@heavybit/shared-lib 2.1.0 → 2.7.0

package/dist/types/knex/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/knex/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAEjC;;;GAGG;AAEH,2CAA2C;AAC3C,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,SAAO,GAAG,IAAI,CAE7E;AAED,iGAAiG;AACjG,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,aAAa,CAEpH;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAG3E;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAGjE;AAED,qCAAqC;AACrC,wBAAgB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,aAAa,CAElH;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAYxI;AAED,wDAAwD;AACxD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,SAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYxF;AAED,0EAA0E;AAC1E,wBAAgB,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAI5D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/knex/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAKjC,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AAEvC;;;GAGG;AAEH;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAYxI;AAED,6FAA6F;AAC7F,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,SAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAG9F;AAED,0EAA0E;AAC1E,wBAAgB,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAI5D"}

package/dist/types/knex/migration-helpers.d.ts

@@ -0,0 +1,28 @@
+import type { Knex } from 'knex';
+/**
+ * Column sets for infrastructure tables, for `.cjs` migrations. Each matches the Drizzle table of
+ * the same purpose in `@heavybit/shared-lib/database` (`outboxTable`, `processedEventsTable`,
+ * `schedulerRunsTable`); a test keeps the two in step.
+ *
+ * @example
+ * await knex.schema.createTable('processed_events', (t) => processedEventsColumns(t, knex));
+ */
+type Builder = Knex.CreateTableBuilder;
+/**
+ * Outbox columns: id, routing_key, exchange, payload, correlation_id, attempts, last_error, created_at,
+ * published_at (+ relay index).
+ */
+export declare function outboxColumns(t: Builder, knex: Knex): void;
+/** Consumer idempotency columns: id, consumer, event_id (unique together), processed_at. */
+export declare function processedEventsColumns(t: Builder, knex: Knex): void;
+/** Scheduler run columns: id, job, run_key (unique together), status, error, started_at, finished_at. */
+export declare function schedulerRunsColumns(t: Builder, knex: Knex): void;
+/**
+ * Index that always leads with the scope column (TEN-4); `columns` follow in order, duplicates of
+ * the scope column are dropped.
+ *
+ * @example scopedIndex(t, 'workspace_id', ['status', 'created_at'])
+ */
+export declare function scopedIndex(t: Builder | Knex.AlterTableBuilder, scopeColumn: string, columns?: string[], indexName?: string): void;
+export {};
+//# sourceMappingURL=migration-helpers.d.ts.map

package/dist/types/knex/migration-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-helpers.d.ts","sourceRoot":"","sources":["../../../src/knex/migration-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAIjC;;;;;;;GAOG;AAEH,KAAK,OAAO,GAAG,IAAI,CAAC,kBAAkB,CAAC;AAGvC;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAW1D;AAED,4FAA4F;AAC5F,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAOnE;AAED,yGAAyG;AACzG,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAUjE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,iBAAiB,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,EAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAGtI"}

package/dist/types/logging/redact.d.ts

@@ -11,13 +11,13 @@ export declare const DEFAULT_ALLOW_KEYS: readonly string[];
 /** The marker that replaces a secret value. */
 export declare const REDACTED = "[REDACTED]";
 /**
- * Masks every digit except the last four (log rule; the UI uses `maskPhone` from common).
+ * Masks every digit except the last four; the same rule as `maskPhone` in common (one rule for logs and UI).
  *
  * @param value A phone number in any format.
  * @returns e.g. `********5678`; values with fewer than 5 digits are fully masked.
  * @example maskPhoneForLog('15551234567') // '*******4567'
  */
-export declare function maskPhoneForLog(value: string): string;
+export declare const maskPhoneForLog: (value: string) => string;
 /**
  * Masks phone-number-looking runs inside free text.
  *

package/dist/types/logging/redact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../../src/logging/redact.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAGhD,CAAC;AAEF,4GAA4G;AAC5G,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAAwF,CAAC;AAQzI,+CAA+C;AAC/C,eAAO,MAAM,QAAQ,eAAe,CAAC;AAGrC;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAWD,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,GAAE,SAAS,MAAM,EAAO,EAAE,SAAS,GAAE,SAAS,MAAM,EAAuB,GAAG,aAAa,CAgBvI;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,KAAK,SAAI,GAAG,OAAO,CAYzF"}
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../../src/logging/redact.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAGhD,CAAC;AAEF,4GAA4G;AAC5G,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAAwF,CAAC;AAQzI,+CAA+C;AAC/C,eAAO,MAAM,QAAQ,eAAe,CAAC;AAGrC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAkB,CAAC;AAEpE;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAWD,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,GAAE,SAAS,MAAM,EAAO,EAAE,SAAS,GAAE,SAAS,MAAM,EAAuB,GAAG,aAAa,CAgBvI;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,KAAK,SAAI,GAAG,OAAO,CAYzF"}

package/dist/types/messaging/base-consumer.d.ts

@@ -0,0 +1,33 @@
+import type { InboundMessage, MessageConsumer, SubscriptionOptions } from './consumer.js';
+/** Everything a subscription needs except the handler, which a {@link BaseConsumer} subclass supplies. */
+export type ConsumerDefinition<T, TTx> = Omit<SubscriptionOptions<T, TTx>, 'handler'>;
+/**
+ * Base for a service's queue consumers (one class per queue in `src/consumers/`). The subclass declares
+ * its queue, bindings, payload schema, retry policy, dedupe and scope in the constructor and implements
+ * {@link BaseConsumer.handle}; `worker.ts` registers it. Validation, dedupe, retries, dead-lettering and
+ * context restore are done by {@link MessageConsumer}.
+ *
+ * @typeParam T Validated payload type.
+ * @typeParam TTx Dedupe transaction type (`DbExecutor` with `ProcessedEventsDeduper`).
+ * @example
+ * class ThingCreatedConsumer extends BaseConsumer<ThingCreated, DbExecutor> {
+ *   constructor(private readonly things: ThingService, dedupe: ProcessedEventsDeduper) {
+ *     super({ queue: 'thing-created', bindings: [{ exchange: 'events', routingKey: 'thing.created' }],
+ *       schema: thingCreatedSchema, dedupe, scopeFrom: (d) => ({ tenantId: d.tenantId }) });
+ *   }
+ *   protected handle({ data, tx, scope }: InboundMessage<ThingCreated, DbExecutor>) { return this.things.onCreated(scope!, data, tx!); }
+ * }
+ */
+export declare abstract class BaseConsumer<T, TTx = undefined> {
+    protected readonly definition: ConsumerDefinition<T, TTx>;
+    protected constructor(definition: ConsumerDefinition<T, TTx>);
+    /** Handles one validated, de-duplicated message. Throw to retry (or a non-retryable error to dead-letter). */
+    protected abstract handle(message: InboundMessage<T, TTx>): Promise<void>;
+    /**
+     * Subscribes this consumer.
+     *
+     * @param consumer The service's {@link MessageConsumer}.
+     */
+    register(consumer: MessageConsumer): Promise<void>;
+}
+//# sourceMappingURL=base-consumer.d.ts.map

package/dist/types/messaging/base-consumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-consumer.d.ts","sourceRoot":"","sources":["../../../src/messaging/base-consumer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAE1F,0GAA0G;AAC1G,MAAM,MAAM,kBAAkB,CAAC,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,mBAAmB,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC;AAEtF;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,YAAY,CAAC,CAAC,EAAE,GAAG,GAAG,SAAS;IAC7B,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC,CAAC,EAAE,GAAG,CAAC;IAA/E,SAAS,aAAgC,UAAU,EAAE,kBAAkB,CAAC,CAAC,EAAE,GAAG,CAAC;IAE/E,8GAA8G;IAC9G,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAEzE;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAGnD"}

package/dist/types/messaging/consumer.d.ts

@@ -1,55 +1,93 @@
 import type { ConsumeMessage } from 'amqplib';
-import type { ZodTypeAny } from 'zod';
+import type { ZodType, ZodTypeDef } from 'zod';
 import type { EventEnvelope, Logger } from '../types/index.js';
 import type { AmqpConnection } from './connection.js';
-import type { IdempotencyStore } from './idempotency.js';
+import type { EventDeduper } from './idempotency.js';
 import { type Topology } from './topology.js';
+/** One exchange binding of a subscription queue. */
 export interface Binding {
-    /** `events` (topic, pattern keys like `auth.user.*`) or `commands` (exact command name). */
+    /** `events` (topic, pattern keys like `thing.*`) or `commands` (exact command name). */
     exchange: 'events' | 'commands';
     routingKey: string;
 }
-export interface InboundMessage<T = unknown> {
-    /** Envelope `data`, validated against `schema` when one is given. */
+/** Scope values restored from a message, e.g. `{ tenantId: '01J…' }`; the app names the keys. */
+export type MessageScope = Readonly<Record<string, string>>;
+/** What a consumer handler receives for one delivery. */
+export interface InboundMessage<T = unknown, TTx = undefined> {
+    /** Payload (envelope `data` without the reserved fields), validated against `schema` when given. */
     data: T;
     envelope: EventEnvelope | null;
+    /** Envelope event id, else the AMQP `messageId`. */
+    eventId: string | undefined;
     routingKey: string;
-    /** How many times this message has been retried before (0 on first delivery). */
+    /** Delivery attempt, 1-based. */
     attempt: number;
+    /** The dedupe ledger's open transaction (write through it so effects and ledger commit together). */
+    tx: TTx | undefined;
+    /** Scope restored by `scopeFrom`; also set as the request context's `scopes`. */
+    scope: MessageScope | undefined;
     raw: ConsumeMessage;
 }
-export interface SubscriptionOptions<T = unknown> {
-    /** Logical queue name; the environment prefix is added. Convention: `<service>:<source>.<topic>`. */
+/** One durable subscription: queue purpose, bindings, handler and delivery policy. */
+export interface SubscriptionOptions<T = unknown, TTx = undefined> {
+    /** Queue purpose; the physical queue is `{prefix}.{service}.{purpose}`. */
     queue: string;
     bindings: Binding[];
-    handler: (message: InboundMessage<T>) => Promise<void>;
-    /** Validates `data`; failures dead-letter immediately (a bad payload never succeeds on retry). */
-    schema?: ZodTypeAny;
+    handler: (message: InboundMessage<T, TTx>) => Promise<void>;
+    /** Validates the payload; failures dead-letter immediately (a bad payload never succeeds on retry). */
+    schema?: ZodType<T, ZodTypeDef, unknown>;
     prefetch?: number;
-    /** Delay before each retry. Length = max retries. Default: 1s, 5s, 25s. */
-    retryDelaysMs?: number[];
-    /** Enables duplicate suppression keyed on `<queue>:<eventId>`. */
-    idempotency?: IdempotencyStore;
-    idempotencyTtlSec?: number;
+    /** Total deliveries before dead-lettering (default 5). Retry n waits `retryBaseDelayMs × 2^n`. */
+    maxAttempts?: number;
+    /** Base of the exponential retry delay (default 1000 ms → 2 s, 4 s, 8 s, 16 s). */
+    retryBaseDelayMs?: number;
+    /** Duplicate suppression keyed on `({service}.{purpose}, eventId)`; a message without an id dead-letters. */
+    dedupe?: EventDeduper<TTx>;
+    /**
+     * Re-establishes the scope (tenant) the message belongs to from its payload (TEN-7). Every returned
+     * value must be a non-empty string, or the message dead-letters.
+     *
+     * @example scopeFrom: (d) => ({ tenantId: d.tenantId })
+     */
+    scopeFrom?: (data: T) => Record<string, string | null | undefined>;
 }
+/** Total deliveries before a failing message is dead-lettered. */
+export declare const DEFAULT_MAX_ATTEMPTS = 5;
+/** Base of the exponential retry delay (retry n waits base × 2^n). */
+export declare const DEFAULT_RETRY_BASE_DELAY_MS = 1000;
 /**
- * Durable subscriptions with bounded retries and dead-lettering:
+ * Retry delays for `maxAttempts` deliveries: `base × 2^n` for n = 1 … maxAttempts − 1.
+ *
+ * @example retryDelays(5, 1000) // [2000, 4000, 8000, 16000]
+ */
+export declare function retryDelays(maxAttempts?: number, baseMs?: number): number[];
+/**
+ * Durable subscriptions with manual ack, bounded exponential retries and dead-lettering:
  *
  *   <queue> ──fail──▶ <queue>.retry.<delay>  (TTL, dead-letters back into <queue>)
- *           ──fail after last retry / non-retryable──▶ <queue>.dlq
+ *           ──last attempt / non-retryable / invalid──▶ service DLX ──▶ <queue>.dlq
  *
- * One fixed TTL per retry queue avoids head-of-line blocking of per-message TTLs.
+ * One fixed TTL per retry queue avoids head-of-line blocking of per-message TTLs. The main queue also
+ * names the service DLX, so broker-side rejects land in the same DLQ. Each message runs inside a request
+ * context carrying its correlation id, actor and restored scope.
  */
 export declare class MessageConsumer {
     private readonly connection;
     private readonly topology;
+    private readonly service;
     private readonly handles;
     private readonly logger;
-    constructor(connection: AmqpConnection, topology: Topology, logger?: Logger);
     /** Physical DLQ names for every subscription (for monitoring). */
     readonly deadLetterQueues: string[];
-    subscribe<T = unknown>(options: SubscriptionOptions<T>): Promise<void>;
+    constructor(connection: AmqpConnection, topology: Topology, service: string, logger?: Logger);
+    subscribe<T = unknown, TTx = undefined>(options: SubscriptionOptions<T, TTx>): Promise<void>;
+    private declare;
     private dispatch;
+    /** Parses, validates and extracts scope; throws `Rejected` for messages that can never succeed. */
+    private prepare;
+    private scopeOf;
+    private correlationIdOf;
+    private handle;
     private retryOrDeadLetter;
     private deadLetter;
 }

package/dist/types/messaging/consumer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consumer.d.ts","sourceRoot":"","sources":["../../../src/messaging/consumer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,cAAc,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAGtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,iBAAiB,CAAC;AAErE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAuC,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEnF,MAAM,WAAW,OAAO;IACtB,4FAA4F;IAC5F,QAAQ,EAAE,QAAQ,GAAG,UAAU,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,qEAAqE;IACrE,IAAI,EAAE,CAAC,CAAC;IACR,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,cAAc,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,OAAO;IAC9C,qGAAqG;IACrG,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,kGAAkG;IAClG,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,kEAAkE;IAClE,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAKD;;;;;;;GAOG;AACH,qBAAa,eAAe;IAId,OAAO,CAAC,QAAQ,CAAC,UAAU;IAAkB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAHlF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEH,UAAU,EAAE,cAAc,EAAmB,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM;IAI7G,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAM;IAEnC,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;YAiC9D,QAAQ;IAgDtB,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,UAAU;CASnB"}
+{"version":3,"file":"consumer.d.ts","sourceRoot":"","sources":["../../../src/messaging/consumer.ts"],"names":[],"mappings":"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"}

package/dist/types/messaging/envelope.d.ts

@@ -1,16 +1,55 @@
-import type { EventEnvelope } from '../types/index.js';
+import type { EnvelopeData, EventEnvelope } from '../types/index.js';
+/** Names reserved in an envelope's `data`; a payload field with one of these names is overwritten. */
+export declare const RESERVED_ENVELOPE_FIELDS: readonly ["eventId", "version", "actorUserId"];
+/** AMQP header that carries the correlation id between services. */
+export declare const CORRELATION_HEADER: "x-correlation-id";
+/**
+ * Optional envelope values and transport metadata.
+ *
+ * @example { actorUserId: user.id, version: 2 }
+ */
 export interface EnvelopeMeta {
-    actorId?: string | null;
-    correlationId?: string;
-    aggregate?: {
-        type: string;
-        id: string;
-        version?: number;
-    };
-    version?: number;
-    /** Deterministic ID for idempotent re-publishing (defaults to a new ULID). */
+    /** Deterministic id for idempotent re-publishing; defaults to a new ULID. */
     eventId?: string;
+    /** Payload schema version; defaults to 1. */
+    version?: number;
+    /** Defaults to the request context's `userId`; pass `null` for the system. */
+    actorUserId?: string | null;
+    /** Sent as the `x-correlation-id` header (not part of the body); defaults to the request context's. */
+    correlationId?: string;
 }
-export declare function buildEnvelope<T>(type: string, data: T, source: string, meta?: EnvelopeMeta): EventEnvelope<T>;
+/**
+ * Builds `{ routingKey, data: { ...payload, eventId, version, actorUserId? }, timestamp }`.
+ *
+ * @param routingKey Event or command name.
+ * @param data Payload fields (an object); {@link RESERVED_ENVELOPE_FIELDS} are set by the envelope.
+ * @param meta Optional id, version and actor.
+ * @returns The envelope.
+ * @example const envelope = buildEnvelope('thing.created', { thingId }, { actorUserId: user.id });
+ */
+export declare function buildEnvelope<T extends object>(routingKey: string, data: T, meta?: EnvelopeMeta): EventEnvelope<T>;
+/**
+ * True when `value` has the envelope shape (routing key, timestamp and `data.eventId`).
+ *
+ * @param value Parsed message body.
+ * @returns Whether it is an {@link EventEnvelope}.
+ */
 export declare function isEnvelope(value: unknown): value is EventEnvelope;
+/**
+ * Splits an envelope's `data` into the payload and the reserved fields.
+ *
+ * @param envelope A received envelope.
+ * @returns `payload` (without reserved fields) and `meta` ({@link EnvelopeData}).
+ */
+export declare function splitEnvelopeData(envelope: EventEnvelope): {
+    payload: Record<string, unknown>;
+    meta: EnvelopeData;
+};
+/**
+ * The correlation id to send: the explicit one, else the active request context's.
+ *
+ * @param meta Optional explicit value.
+ * @returns The id, or undefined outside a request/consumer context.
+ */
+export declare function outgoingCorrelationId(meta?: Pick<EnvelopeMeta, 'correlationId'>): string | undefined;
 //# sourceMappingURL=envelope.d.ts.map

package/dist/types/messaging/envelope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../../src/messaging/envelope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,aAAa,CAAC,CAAC,CAAC,CAYjH;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAGjE"}
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../../src/messaging/envelope.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAErE,sGAAsG;AACtG,eAAO,MAAM,wBAAwB,gDAAiD,CAAC;AAEvF,oEAAoE;AACpE,eAAO,MAAM,kBAAkB,oBAAiC,CAAC;AAEjE;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uGAAuG;IACvG,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAE,YAAiB,GAAG,aAAa,CAAC,CAAC,CAAC,CAQtH;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAOjE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,CAGnH;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,eAAe,CAAC,GAAG,MAAM,GAAG,SAAS,CAEpG"}

package/dist/types/messaging/idempotency.d.ts

@@ -1,7 +1,44 @@
 import type { Redis } from 'ioredis';
+import type { RedisKeyspace } from '../cache/keyspace.js';
+import type { DbExecutor } from '../database/scoped-repository.js';
+import { type ProcessedEventsTable } from '../database/tables.js';
+/** Result of {@link EventDeduper.run}. */
+export type DedupeOutcome = 'processed' | 'duplicate';
+/**
+ * Runs a consumer's work at most once per `(consumer, eventId)`. At-least-once delivery means duplicates;
+ * a deduper turns them into no-ops.
+ *
+ * @typeParam TTx What `work` receives: the open transaction for a database ledger, `undefined` otherwise.
+ */
+export interface EventDeduper<TTx = unknown> {
+    /**
+     * @param consumer Stable consumer name (e.g. `{service}.{purpose}`).
+     * @param eventId The message's event id.
+     * @param work The handler; it throws to fail (nothing is recorded, so a retry runs it again).
+     * @returns `processed`, or `duplicate` when the event was already handled (work not called).
+     */
+    run(consumer: string, eventId: string, work: (tx: TTx) => Promise<void>): Promise<DedupeOutcome>;
+}
+/** True for a MySQL duplicate-key error, also when Drizzle wraps it in `cause`. */
+export declare function isDuplicateKeyError(error: unknown): boolean;
+/**
+ * Database ledger (`processed_events`, unique `(consumer, event_id)`): the ledger row and the handler's
+ * writes commit in one transaction, so an event is recorded as processed if and only if its effects
+ * commit. A concurrent duplicate blocks on the unique key until the first commits, then is skipped.
+ *
+ * @example const dedupe = new ProcessedEventsDeduper(db); // handler gets `tx` and writes through it
+ */
+export declare class ProcessedEventsDeduper implements EventDeduper<DbExecutor> {
+    private readonly db;
+    private readonly table;
+    constructor(db: DbExecutor, table?: ProcessedEventsTable);
+    run(consumer: string, eventId: string, work: (tx: DbExecutor) => Promise<void>): Promise<DedupeOutcome>;
+}
+/** Outcome of {@link IdempotencyStore.begin}. */
 export type ClaimResult = 'claimed' | 'done' | 'in-flight';
 /**
- * At-least-once delivery means duplicates. Consumers claim `consumer:eventId` before handling:
+ * Lease-based claim store for services without a database (Redis). Not transactional with the handler's
+ * effects: prefer {@link ProcessedEventsDeduper} wherever the handler writes to a database.
  * - `claimed`   → process it, then `complete()` (or `abandon()` on failure so a retry can run)
  * - `done`      → already processed; ack and skip
  * - `in-flight` → another worker holds the lease; retry later
@@ -11,14 +48,17 @@ export interface IdempotencyStore {
     complete(key: string, ttlSec: number): Promise<void>;
     abandon(key: string): Promise<void>;
 }
+/** Redis claim store; every key comes from the service keyspace (`{prefix}idem:{key}`). */
 export declare class RedisIdempotencyStore implements IdempotencyStore {
     private readonly redis;
-    private readonly prefix;
-    constructor(redis: Redis, prefix?: string);
+    private readonly keyspace;
+    constructor(redis: Redis, keyspace: RedisKeyspace);
+    private key;
     begin(key: string, leaseSec: number): Promise<ClaimResult>;
     complete(key: string, ttlSec: number): Promise<void>;
     abandon(key: string): Promise<void>;
 }
+/** In-process claim store for tests and single-process tools. */
 export declare class MemoryIdempotencyStore implements IdempotencyStore {
     private readonly entries;
     private read;
@@ -26,4 +66,21 @@ export declare class MemoryIdempotencyStore implements IdempotencyStore {
     complete(key: string, ttlSec: number): Promise<void>;
     abandon(key: string): Promise<void>;
 }
+/** Lease and retention for {@link StoreDeduper}. */
+export interface StoreDeduperOptions {
+    /** How long a claim blocks other workers (default 300 s). */
+    leaseSec?: number;
+    /** How long a completed marker is kept (default 7 days). */
+    ttlSec?: number;
+}
+/**
+ * {@link EventDeduper} over an {@link IdempotencyStore}. A duplicate still in flight elsewhere throws a
+ * retryable 503, so the consumer retries it later instead of acking it unprocessed.
+ */
+export declare class StoreDeduper implements EventDeduper<undefined> {
+    private readonly store;
+    private readonly options;
+    constructor(store: IdempotencyStore, options?: StoreDeduperOptions);
+    run(consumer: string, eventId: string, work: (tx: undefined) => Promise<void>): Promise<DedupeOutcome>;
+}
 //# sourceMappingURL=idempotency.d.ts.map

package/dist/types/messaging/idempotency.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../../src/messaging/idempotency.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAKD,qBAAa,qBAAsB,YAAW,gBAAgB;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK;IAAS,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAArC,KAAK,EAAE,KAAK,EAAmB,MAAM,SAAU;IAEtE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAO1D,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAK1C;AAED,qBAAa,sBAAuB,YAAW,gBAAgB;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2D;IAEnF,OAAO,CAAC,IAAI;IASN,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAS1D,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG1C"}
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../../src/messaging/idempotency.ts"],"names":[],"mappings":"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"}

package/dist/types/messaging/index.d.ts

@@ -10,19 +10,26 @@ export * from './topology.js';
 export * from './envelope.js';
 export * from './publisher.js';
 export * from './consumer.js';
+export * from './base-consumer.js';
 export * from './idempotency.js';
 export * from './rpc.js';
 export * from './outbox.js';
 export * from './monitor.js';
 export * from './staff-notifier.js';
 export * from './staff-recipients.js';
+/** Inputs for {@link createMessaging}; all values come from the service config. */
 export interface MessagingOptions {
+    /** AMQP URL (`RABBITMQ_URL`, or built by `amqpUrlFromEnv(env)`). */
     url: string;
+    /** App slug: names the exchanges. */
     app: string;
+    /** Environment prefix (`QUEUE_PREFIX`). */
     prefix: string;
+    /** This service's name: names its queues and dead-letter exchange. */
     service: string;
     logger?: Logger;
 }
+/** One service's wired messaging components on a shared connection. */
 export interface Messaging {
     topology: Topology;
     connection: AmqpConnection;

package/dist/types/messaging/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/messaging/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9D,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AAEtC,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,cAAc,CAAC;IAC3B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,YAAY,CAAC;IACtB,0FAA0F;IAC1F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CA0BpE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/messaging/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9D,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AAEtC,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,cAAc,CAAC;IAC3B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,YAAY,CAAC;IACtB,0FAA0F;IAC1F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CA0BpE"}

package/dist/types/messaging/outbox.d.ts

@@ -1,51 +1,91 @@
-import type { Knex } from 'knex';
+import { DEFAULT_OUTBOX_TABLE } from '../database/table-names.js';
+import { type OutboxExchange, type OutboxTable } from '../database/tables.js';
+import type { DbExecutor } from '../database/scoped-repository.js';
 import type { EventEnvelope, Logger } from '../types/index.js';
+import { type EnvelopeMeta } from './envelope.js';
 import { type CommandBus, type EventBus } from './publisher.js';
-export declare const DEFAULT_OUTBOX_TABLE = "event_outbox";
-export type OutboxKind = 'event' | 'command';
-/** Outbox `routing_key` column value: the event type, or `command:<name>` for commands. */
-export declare function outboxRoutingKey(envelope: Pick<EventEnvelope, 'type'>, kind?: OutboxKind): string;
+export { DEFAULT_OUTBOX_TABLE };
+/** Options for {@link enqueueOutbox}. */
+export interface EnqueueOptions extends EnvelopeMeta {
+    /** `events` (default, topic fan-out) or `commands` (direct, one owner). */
+    exchange?: OutboxExchange;
+    /** A service-specific outbox table; defaults to `event_outbox`. */
+    table?: OutboxTable;
+}
 /**
- * Transactional outbox: write the domain change and the event in one DB transaction, then a
- * relay publishes pending rows with broker confirms. Closes the "row committed, event lost"
- * gap of publish-after-commit. Consumers must be idempotent (they are: see IdempotencyStore).
+ * Transactional outbox: stages a message in the caller's transaction, so it is published if and only if
+ * the domain change commits. The {@link OutboxRelay} publishes it later with broker confirms. The
+ * correlation id (explicit, else the request context's) is stored with the row and sent as a header.
  *
- * Table (see `createOutboxTable` in `@heavybit/shared-lib/knex`):
- *   id CHAR(26) PK = eventId, routing_key, payload JSON, attempts, last_error, created_at, published_at
+ * @param tx The caller's open Drizzle transaction (or db handle for a single-statement change).
+ * @param routingKey Event or command name.
+ * @param data Payload fields.
+ * @param options Exchange, envelope meta and table.
+ * @returns The staged envelope.
+ * @example await db.transaction(async (tx) => { await repo.insert(ctx, row, { tx }); await enqueueOutbox(tx, 'thing.created', { thingId: row.id }); });
  */
-export declare function enqueueOutbox(db: Knex | Knex.Transaction, envelope: EventEnvelope, options?: {
-    kind?: OutboxKind;
-    table?: string;
-}): Promise<void>;
+export declare function enqueueOutbox<T extends object>(tx: DbExecutor, routingKey: string, data: T, options?: EnqueueOptions): Promise<EventEnvelope<T>>;
+/** What one relay batch did; passed to {@link OutboxRelayOptions.onMetrics}. */
+export interface OutboxBatchMetrics {
+    /** Rows published in this batch. */
+    published: number;
+    /** Rows that failed (broker down or unroutable) and stay pending. */
+    failed: number;
+    /** Age in ms of the oldest pending row when the batch started (0 when nothing was pending). */
+    lagMs: number;
+}
+/** Dependencies and tuning for {@link OutboxRelay}. */
 export interface OutboxRelayOptions {
-    knex: Knex;
+    db: DbExecutor;
     bus: EventBus & CommandBus;
-    table?: string;
+    table?: OutboxTable;
+    /** Rows per batch (default 100). */
     batchSize?: number;
-    /** Safety-net poll interval; `trigger()` after commits gives low latency. */
+    /** Poll interval when healthy (default 2000 ms); `trigger()` after commits gives low latency. */
     intervalMs?: number;
+    /** Ceiling for the exponential back-off after failed batches (default 60 000 ms). */
+    maxBackoffMs?: number;
+    /** Called after every batch, e.g. to export relay lag as a gauge. */
+    onMetrics?: (metrics: OutboxBatchMetrics) => void;
     logger?: Logger;
 }
+/**
+ * Publishes pending outbox rows in id (= time) order. Each batch locks its rows with
+ * `FOR UPDATE SKIP LOCKED`, so several replicas can relay at once without double-publishing, and marks a
+ * row published only after the broker confirms it. Consumers still dedupe: a crash between confirm and
+ * commit re-sends the row.
+ *
+ * Failures: an unroutable command stays pending and the batch continues; a broker error stops the batch
+ * (keeping order) and the poll interval backs off exponentially until a batch succeeds.
+ */
 export declare class OutboxRelay {
     private readonly options;
     private timer;
     private running;
     private rerun;
+    private failures;
     private readonly logger;
     private readonly table;
     constructor(options: OutboxRelayOptions);
+    /** Starts polling. */
     start(): void;
+    /** Stops polling (an in-flight batch finishes). */
     stop(): void;
+    /** Delay before the next poll: the interval, doubled per consecutive failed batch, capped. */
+    nextDelayMs(): number;
     /** Publishes pending rows now. Concurrent triggers coalesce into one follow-up run. */
     trigger(): Promise<void>;
-    /** One batch. Returns how many rows were published. */
-    flush(): Promise<number>;
+    /** One batch. */
+    flush(): Promise<OutboxBatchMetrics>;
+    /** Deletes published rows older than `olderThanDays`; returns how many were removed. */
+    prune(olderThanDays?: number): Promise<number>;
+    private lockPending;
+    private publish;
+    private schedule;
     /**
      * Logged on the 1st, 2nd, 4th, 8th… failure of a row (the attempt count before this one is in `attempts`),
-     * so a queue that stays missing for hours is still visible without a line every tick.
+     * so a queue that stays missing for hours is still visible without a line every poll.
      */
     private reportUnroutable;
-    /** Deletes published rows older than `olderThanDays`. */
-    prune(olderThanDays?: number): Promise<number>;
 }
 //# sourceMappingURL=outbox.d.ts.map

package/dist/types/messaging/outbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"outbox.d.ts","sourceRoot":"","sources":["../../../src/messaging/outbox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAEjC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAqB,KAAK,UAAU,EAAE,KAAK,QAAQ,EAA+B,MAAM,gBAAgB,CAAC;AAEhH,eAAO,MAAM,oBAAoB,iBAAiB,CAAC;AAEnD,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;AAI7C,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,EAAE,IAAI,GAAE,UAAoB,GAAG,MAAM,CAE1G;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,UAAU,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ5J;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,WAAW;IAOV,OAAO,CAAC,QAAQ,CAAC,OAAO;IANpC,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEF,OAAO,EAAE,kBAAkB;IAKxD,KAAK,IAAI,IAAI;IAMb,IAAI,IAAI,IAAI;IAKZ,uFAAuF;IACjF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB9B,uDAAuD;IACjD,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAwC9B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAQxB,yDAAyD;IACnD,KAAK,CAAC,aAAa,SAAI,GAAG,OAAO,CAAC,MAAM,CAAC;CAIhD"}
+{"version":3,"file":"outbox.d.ts","sourceRoot":"","sources":["../../../src/messaging/outbox.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAA2B,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACvG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAEnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAwC,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AACxF,OAAO,EAAqB,KAAK,UAAU,EAAE,KAAK,QAAQ,EAA+B,MAAM,gBAAgB,CAAC;AAEhH,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAEhC,yCAAyC;AACzC,MAAM,WAAW,cAAe,SAAQ,YAAY;IAClD,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,mEAAmE;IACnE,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAY1J;AAED,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,KAAK,EAAE,MAAM,CAAC;CACf;AAED,uDAAuD;AACvD,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,UAAU,CAAC;IACf,GAAG,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC3B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iGAAiG;IACjG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;;;GAQG;AACH,qBAAa,WAAW;IAQV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAPpC,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,OAAO,CAA4C;IAC3D,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;gBAEP,OAAO,EAAE,kBAAkB;IAKxD,sBAAsB;IACtB,KAAK,IAAI,IAAI;IAKb,mDAAmD;IACnD,IAAI,IAAI,IAAI;IAKZ,8FAA8F;IAC9F,WAAW,IAAI,MAAM;IAKrB,uFAAuF;IACjF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB9B,iBAAiB;IACX,KAAK,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAuC1C,wFAAwF;IAClF,KAAK,CAAC,aAAa,SAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAO/C,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,QAAQ;IAMhB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;CAOzB"}