@vytches/ddd-messaging 0.28.0 → 0.29.2

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=require("@vytches/ddd-logging"),d=require("@vytches/ddd-utils");var o=(i=>(i.PENDING="PENDING",i.PROCESSING="PROCESSING",i.PROCESSED="PROCESSED",i.FAILED="FAILED",i))(o||{}),g=(i=>(i.LOW="low",i.NORMAL="normal",i.HIGH="high",i.CRITICAL="critical",i))(g||{});class p{scheduleRetry(e,t){return Promise.resolve()}}class c{static createMessage(e,t,s){const r={id:d.LibUtils.getUUID(),messageType:e,payload:t,metadata:s?.metadata||{},status:o.PENDING,attempts:0,createdAt:new Date,priority:s?.priority||g.NORMAL};return s?.processAfter&&(r.processAfter=s.processAfter),r}static createDelayedMessage(e,t,s,r){const a=new Date(Date.now()+s);return c.createMessage(e,t,{...r,processAfter:a})}static createHighPriorityMessage(e,t,s){return c.createMessage(e,t,{...s,priority:g.HIGH})}static createFromIntegrationEvent(e,t){const s={metadata:{...e.metadata||{},...t?.metadata||{}}};return t?.priority&&(s.priority=t.priority),t?.processAfter&&(s.processAfter=t.processAfter),c.createMessage(`integration_event:${e.eventName}`,e.payload,s)}}class y{constructor(e,t={}){this.handlers=new Map,this.middlewares=[],this.isRunning=!1,this.logger=u.Logger.create("OutboxProcessor");const s=t.batchSize??10;if(s>1e4)throw new RangeError(`OutboxProcessor: batchSize must be ≤ 10,000, got ${s}`);if(t.retryBackoff){const{initial:r,multiplier:a,maxDelay:n}=t.retryBackoff;if(r<=0||a<=0||n<=0)throw new RangeError(`OutboxProcessor: retryBackoff fields must be positive numbers (initial=${r}, multiplier=${a}, maxDelay=${n})`)}this.repository=e,this.options={batchSize:s,maxRetries:t.maxRetries??3,processingInterval:t.processingInterval??5e3,priorityOrder:t.priorityOrder??[g.CRITICAL,g.HIGH,g.NORMAL,g.LOW],messageTimeout:t.messageTimeout??3e4,enableLogging:t.enableLogging??!1,retryBackoff:t.retryBackoff}}registerHandler(e,t){this.handlers.set(e,t),this.logger.debug(`Registered handler for message type: ${e}`)}use(e){this.middlewares.push(e),this.logger.debug("Registered middleware")}start(){if(this.isRunning){this.logger.warn("Processor is already running");return}this.isRunning=!0,this.logger.info("Starting outbox processor"),this.scheduleProcessing()}stop(){if(!this.isRunning){this.logger.warn("Processor is not running");return}this.isRunning=!1,this.processingTimer&&(clearTimeout(this.processingTimer),this.processingTimer=void 0),this.logger.info("Stopped outbox processor")}async processBatch(){if(!this.isRunning)return;const[e,t]=await d.safeRun(()=>this.repository.getUnprocessedMessages(this.options.batchSize,this.options.priorityOrder));if(e){const a=e instanceof Error?e.message:String(e);this.logger.error(`Error retrieving messages: ${a}`);return}const s=t;if(!s||!Array.isArray(s)||s.length===0){this.logger.debug("No pending messages to process");return}this.logger.info(`Processing ${s.length} messages`);const r=s.map(a=>this.processMessage(a));await Promise.allSettled(r),this.logger.info(`Completed processing batch of ${s.length} messages`)}async processMessage(e){const[t]=await d.safeRun(async()=>{await this.repository.updateStatus(e.id,o.PROCESSING),await this.buildPipeline(e)(e),await this.repository.updateStatus(e.id,o.PROCESSED),this.logger.debug(`Successfully processed message ${e.id}`)});t&&await this.handleMessageError(e,t)}buildPipeline(e){const t=this.handlers.get(e.messageType);if(!t)throw new Error(`No handler registered for message type: ${e.messageType}`);const s=async r=>{await Promise.race([t.handle(r),new Promise((a,n)=>setTimeout(()=>n(new Error("Message processing timeout")),this.options.messageTimeout))])};return this.middlewares.reduceRight((r,a)=>a(r),s)}async handleMessageError(e,t){try{const s=await this.repository.incrementAttempt(e.id);if(this.logger.warn(`Message ${e.id} failed, attempt ${s}: ${t?.message}`),s>=this.options.maxRetries)await this.repository.updateStatus(e.id,o.FAILED,t),this.logger.error(`Message ${e.id} marked as failed after ${s} attempts`);else if(this.options.retryBackoff){const{initial:r,multiplier:a,maxDelay:n}=this.options.retryBackoff,l=Math.min(r*Math.pow(a,s-1),n),h=new Date(Date.now()+l);await this.repository.updateStatus(e.id,o.PENDING),await this.repository.scheduleRetry(e.id,h),this.logger.info(`Message ${e.id} scheduled for retry in ${l}ms (attempt ${s})`)}else await this.repository.updateStatus(e.id,o.PENDING),this.logger.info(`Message ${e.id} scheduled for retry (attempt ${s+1})`)}catch(s){const r=s instanceof Error?s.message:String(s);this.logger.error(`Error updating message status: ${r}`)}}scheduleProcessing(){this.isRunning&&(this.processingTimer=setTimeout(async()=>{await this.processBatch(),this.scheduleProcessing()},this.options.processingInterval))}log(e){this.options.enableLogging&&this.logger.info(e)}async getStats(){return{isRunning:this.isRunning,batchSize:this.options.batchSize,maxRetries:this.options.maxRetries,processingInterval:this.options.processingInterval,registeredHandlers:Array.from(this.handlers.keys()),middlewareCount:this.middlewares.length}}}class f{constructor(e){this.eventBus=e}async handle(e){const s={eventName:e.messageType.startsWith("integration_event:")?e.messageType.replace("integration_event:",""):e.messageType,eventId:e.id,occurredOn:e.createdAt,version:1,...e.payload,...e.metadata};await this.eventBus.publish(s)}}class m{constructor(e,t={}){this.logger=u.Logger.create("OutboxService"),this.repository=e,this.options={defaultPriority:t.defaultPriority??g.NORMAL,defaultMetadata:t.defaultMetadata??{},autoCleanup:t.autoCleanup??!1,cleanupAfterDays:t.cleanupAfterDays??7,enableLogging:t.enableLogging??!1}}async saveMessage(e,t,s){const r=c.createMessage(e,t,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...s?.metadata},...s}),a=await this.repository.saveMessage(r);return this.logger.debug(`Saved message ${a} of type ${e}`),a}async saveMessages(e){const t=e.map(({messageType:r,payload:a,options:n})=>c.createMessage(r,a,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...n?.metadata},...n})),s=await this.repository.saveBatch(t);return this.logger.debug(`Saved batch of ${e.length} messages`),s}async scheduleMessage(e,t,s,r){const a=c.createDelayedMessage(e,t,s,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...r?.metadata},...r}),n=await this.repository.scheduleMessage(a,a.processAfter);return this.logger.debug(`Scheduled message ${n} of type ${e} for processing in ${s}ms`),n}async saveHighPriorityMessage(e,t,s){return this.saveMessage(e,t,{...s,priority:g.HIGH})}async saveCriticalMessage(e,t,s){return this.saveMessage(e,t,{...s,priority:g.CRITICAL})}async saveDomainEvent(e,t){const s=c.createFromIntegrationEvent({eventName:e.eventName,payload:e,metadata:{eventId:e?.metadata?.eventId,occurredOn:e?.metadata?.occurredOn,version:e?.metadata?.version}},{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...t?.metadata},...t}),r=await this.repository.saveMessage(s);return this.logger.debug(`Saved domain event ${e.eventName} as message ${r}`),r}async getMessage(e){return this.repository.getById(e)}async getPendingMessages(e=100){return this.repository.getUnprocessedMessages(e)}async retryMessage(e){await this.repository.updateStatus(e,o.PENDING),this.logger.info(`Reset message ${e} to pending for retry`)}async retryMessages(e){await this.repository.updateStatusBatch(e,o.PENDING),this.logger.info(`Reset ${e.length} messages to pending for retry`)}async cleanup(e){const t=e??this.options.cleanupAfterDays,s=new Date;s.setDate(s.getDate()-t);const r=await this.repository.deleteByStatusAndAge(s,o.PROCESSED);return this.logger.info(`Cleaned up ${r} processed messages older than ${t} days`),r}async getStats(){const e=this.repository;return e.getMessageCountByStatus?{totalPending:e.getMessageCountByStatus(o.PENDING),totalProcessing:e.getMessageCountByStatus(o.PROCESSING),totalProcessed:e.getMessageCountByStatus(o.PROCESSED),totalFailed:e.getMessageCountByStatus(o.FAILED)}:{totalPending:(await this.repository.getUnprocessedMessages(1e3)).length,totalProcessing:0,totalProcessed:0,totalFailed:0}}log(e){this.options.enableLogging&&this.logger.info(e)}}exports.EventBusOutboxHandler=f;exports.IOutboxRepository=p;exports.MessagePriority=g;exports.MessageStatus=o;exports.OutboxMessageFactory=c;exports.OutboxProcessor=y;exports.OutboxService=m;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=require("@vytches/ddd-logging"),d=require("@vytches/ddd-utils");var n=(i=>(i.PENDING="PENDING",i.PROCESSING="PROCESSING",i.PROCESSED="PROCESSED",i.FAILED="FAILED",i))(n||{}),g=(i=>(i.LOW="low",i.NORMAL="normal",i.HIGH="high",i.CRITICAL="critical",i))(g||{});class p{scheduleRetry(e,t){return Promise.resolve()}resetStaleProcessing(e){return Promise.resolve(0)}}class l{static createMessage(e,t,s){const r={id:d.LibUtils.getUUID(),messageType:e,payload:t,metadata:s?.metadata||{},status:n.PENDING,attempts:0,createdAt:new Date,priority:s?.priority||g.NORMAL};return s?.processAfter&&(r.processAfter=s.processAfter),r}static createDelayedMessage(e,t,s,r){const a=new Date(Date.now()+s);return l.createMessage(e,t,{...r,processAfter:a})}static createHighPriorityMessage(e,t,s){return l.createMessage(e,t,{...s,priority:g.HIGH})}static createFromIntegrationEvent(e,t){const s={metadata:{...e.metadata||{},...t?.metadata||{}}};return t?.priority&&(s.priority=t.priority),t?.processAfter&&(s.processAfter=t.processAfter),l.createMessage(`integration_event:${e.eventName}`,e.payload,s)}}class y{constructor(e,t={}){this.handlers=new Map,this.middlewares=[],this.isRunning=!1,this.logger=u.Logger.create("OutboxProcessor");const s=t.batchSize??10;if(s>1e4)throw new RangeError(`OutboxProcessor: batchSize must be ≤ 10,000, got ${s}`);if(t.retryBackoff){const{initial:o,multiplier:h,maxDelay:c}=t.retryBackoff;if(o<=0||h<=0||c<=0)throw new RangeError(`OutboxProcessor: retryBackoff fields must be positive numbers (initial=${o}, multiplier=${h}, maxDelay=${c})`)}const r=t.messageTimeout??3e4,a=t.crashRecoveryThresholdMs??Math.max(3e5,r);if(a<r)throw new RangeError(`OutboxProcessor: crashRecoveryThresholdMs (${a}) must be ≥ messageTimeout (${r}) to avoid resetting in-flight messages`);this.repository=e,this.options={batchSize:s,maxRetries:t.maxRetries??3,processingInterval:t.processingInterval??5e3,priorityOrder:t.priorityOrder??[g.CRITICAL,g.HIGH,g.NORMAL,g.LOW],messageTimeout:r,enableLogging:t.enableLogging??!1,retryBackoff:t.retryBackoff,messageTypes:t.messageTypes,crashRecoveryIntervalMs:t.crashRecoveryIntervalMs,crashRecoveryThresholdMs:a,adaptiveRepoll:t.adaptiveRepoll??!1,adaptiveRepollMaxConsecutive:t.adaptiveRepollMaxConsecutive??5,adaptiveRepollPauseMs:t.adaptiveRepollPauseMs??50,startupJitterMs:t.startupJitterMs??0,hooks:t.hooks}}safelyInvokeHook(e,t){if(this.options.hooks)try{t()}catch(s){const r=s instanceof Error?s.message:String(s);this.logger.error(`Outbox hook ${e} threw and was ignored: ${r}`)}}registerHandler(e,t){this.handlers.set(e,t),this.logger.debug(`Registered handler for message type: ${e}`)}use(e){this.middlewares.push(e),this.logger.debug("Registered middleware")}start(){if(this.isRunning){this.logger.warn("Processor is already running");return}this.isRunning=!0,this.logger.info("Starting outbox processor");const e=this.options.startupJitterMs>0?Math.floor(Math.random()*this.options.startupJitterMs):0;this.scheduleProcessing(0,this.options.processingInterval+e),this.scheduleCrashRecovery()}stop(){if(!this.isRunning){this.logger.warn("Processor is not running");return}this.isRunning=!1,this.processingTimer&&(clearTimeout(this.processingTimer),this.processingTimer=void 0),this.crashRecoveryTimer&&(clearTimeout(this.crashRecoveryTimer),this.crashRecoveryTimer=void 0),this.logger.info("Stopped outbox processor")}async processBatch(){const e=this.options.batchSize;if(!this.isRunning)return{processed:0,batchSize:e};const[t,s]=await d.safeRun(()=>this.repository.getUnprocessedMessages(e,this.options.priorityOrder,this.options.messageTypes));if(t){const c=t instanceof Error?t.message:String(t);return this.logger.error(`Error retrieving messages: ${c}`),{processed:0,batchSize:e}}const r=s;if(!r||!Array.isArray(r)||r.length===0)return this.logger.debug("No pending messages to process"),{processed:0,batchSize:e};this.logger.info(`Processing ${r.length} messages`);const a=Date.now(),h=(await Promise.allSettled(r.map(c=>this.processMessage(c)))).filter(c=>c.status==="rejected"||c.status==="fulfilled"&&c.value===!1).length;return this.logger.info(`Completed processing batch of ${r.length} messages`),this.safelyInvokeHook("onBatchComplete",()=>this.options.hooks?.onBatchComplete?.({processed:r.length,failed:h,batchSize:e,durationMs:Date.now()-a})),{processed:r.length,batchSize:e}}async processMessage(e){const[t]=await d.safeRun(async()=>{await this.repository.updateStatus(e.id,n.PROCESSING),await this.buildPipeline(e)(e),await this.repository.updateStatus(e.id,n.PROCESSED),this.logger.debug(`Successfully processed message ${e.id}`)});return t?(await this.handleMessageError(e,t),!1):!0}buildPipeline(e){const t=this.handlers.get(e.messageType);if(!t)throw new Error(`No handler registered for message type: ${e.messageType}`);const s=async r=>{await Promise.race([t.handle(r),new Promise((a,o)=>setTimeout(()=>o(new Error("Message processing timeout")),this.options.messageTimeout))])};return this.middlewares.reduceRight((r,a)=>a(r),s)}async handleMessageError(e,t){try{const s=await this.repository.incrementAttempt(e.id);if(this.logger.warn(`Message ${e.id} failed, attempt ${s}: ${t?.message}`),this.safelyInvokeHook("onMessageFailed",()=>this.options.hooks?.onMessageFailed?.(e,t,s)),s>=this.options.maxRetries)await this.repository.updateStatus(e.id,n.FAILED,t),this.logger.error(`Message ${e.id} marked as failed after ${s} attempts`),this.safelyInvokeHook("onPermanentFailure",()=>this.options.hooks?.onPermanentFailure?.(e,t));else if(this.options.retryBackoff){const{initial:r,multiplier:a,maxDelay:o}=this.options.retryBackoff,h=Math.min(r*Math.pow(a,s-1),o),c=new Date(Date.now()+h);await this.repository.updateStatus(e.id,n.PENDING),await this.repository.scheduleRetry(e.id,c),this.logger.info(`Message ${e.id} scheduled for retry in ${h}ms (attempt ${s})`)}else await this.repository.updateStatus(e.id,n.PENDING),this.logger.info(`Message ${e.id} scheduled for retry (attempt ${s+1})`)}catch(s){const r=s instanceof Error?s.message:String(s);this.logger.error(`Error updating message status: ${r}`)}}scheduleProcessing(e=0,t=this.options.processingInterval){this.isRunning&&(this.processingTimer=setTimeout(async()=>{const s=await this.processBatch();if(this.options.adaptiveRepoll&&s.processed>0&&s.processed>=s.batchSize){const a=e+1,o=a>this.options.adaptiveRepollMaxConsecutive?this.options.adaptiveRepollPauseMs:0;this.scheduleProcessing(a,o)}else this.scheduleProcessing(0,this.options.processingInterval)},t))}scheduleCrashRecovery(){!this.isRunning||this.options.crashRecoveryIntervalMs===void 0||(this.crashRecoveryTimer=setTimeout(async()=>{await this.runCrashRecovery(),this.scheduleCrashRecovery()},this.options.crashRecoveryIntervalMs))}async runCrashRecovery(){const e=new Date(Date.now()-this.options.crashRecoveryThresholdMs),[t,s]=await d.safeRun(()=>this.repository.resetStaleProcessing(e));if(t){const r=t instanceof Error?t.message:String(t);this.logger.error(`Crash recovery failed: ${r}`);return}s&&s>0&&this.logger.warn(`Crash recovery reset ${s} stale PROCESSING message(s) to PENDING`)}log(e){this.options.enableLogging&&this.logger.info(e)}async getStats(){return{isRunning:this.isRunning,batchSize:this.options.batchSize,maxRetries:this.options.maxRetries,processingInterval:this.options.processingInterval,registeredHandlers:Array.from(this.handlers.keys()),middlewareCount:this.middlewares.length}}}class f{constructor(e){this.eventBus=e}async handle(e){const s={eventName:e.messageType.startsWith("integration_event:")?e.messageType.replace("integration_event:",""):e.messageType,eventId:e.id,occurredOn:e.createdAt,version:1,...e.payload,...e.metadata};await this.eventBus.publish(s)}}class m{constructor(e,t={}){this.logger=u.Logger.create("OutboxService"),this.repository=e,this.options={defaultPriority:t.defaultPriority??g.NORMAL,defaultMetadata:t.defaultMetadata??{},autoCleanup:t.autoCleanup??!1,cleanupAfterDays:t.cleanupAfterDays??7,enableLogging:t.enableLogging??!1}}async saveMessage(e,t,s){const r=l.createMessage(e,t,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...s?.metadata},...s}),a=await this.repository.saveMessage(r);return this.logger.debug(`Saved message ${a} of type ${e}`),a}async saveMessages(e){const t=e.map(({messageType:r,payload:a,options:o})=>l.createMessage(r,a,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...o?.metadata},...o})),s=await this.repository.saveBatch(t);return this.logger.debug(`Saved batch of ${e.length} messages`),s}async scheduleMessage(e,t,s,r){const a=l.createDelayedMessage(e,t,s,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...r?.metadata},...r}),o=await this.repository.scheduleMessage(a,a.processAfter);return this.logger.debug(`Scheduled message ${o} of type ${e} for processing in ${s}ms`),o}async saveHighPriorityMessage(e,t,s){return this.saveMessage(e,t,{...s,priority:g.HIGH})}async saveCriticalMessage(e,t,s){return this.saveMessage(e,t,{...s,priority:g.CRITICAL})}async saveDomainEvent(e,t){const s=l.createFromIntegrationEvent({eventName:e.eventName,payload:e,metadata:{eventId:e?.metadata?.eventId,occurredOn:e?.metadata?.occurredOn,version:e?.metadata?.version}},{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...t?.metadata},...t}),r=await this.repository.saveMessage(s);return this.logger.debug(`Saved domain event ${e.eventName} as message ${r}`),r}async getMessage(e){return this.repository.getById(e)}async getPendingMessages(e=100){return this.repository.getUnprocessedMessages(e)}async retryMessage(e){await this.repository.updateStatus(e,n.PENDING),this.logger.info(`Reset message ${e} to pending for retry`)}async retryMessages(e){await this.repository.updateStatusBatch(e,n.PENDING),this.logger.info(`Reset ${e.length} messages to pending for retry`)}async cleanup(e){const t=e??this.options.cleanupAfterDays,s=new Date;s.setDate(s.getDate()-t);const r=await this.repository.deleteByStatusAndAge(s,n.PROCESSED);return this.logger.info(`Cleaned up ${r} processed messages older than ${t} days`),r}async getStats(){const e=this.repository;return e.getMessageCountByStatus?{totalPending:e.getMessageCountByStatus(n.PENDING),totalProcessing:e.getMessageCountByStatus(n.PROCESSING),totalProcessed:e.getMessageCountByStatus(n.PROCESSED),totalFailed:e.getMessageCountByStatus(n.FAILED)}:{totalPending:(await this.repository.getUnprocessedMessages(1e3)).length,totalProcessing:0,totalProcessed:0,totalFailed:0}}log(e){this.options.enableLogging&&this.logger.info(e)}}exports.EventBusOutboxHandler=f;exports.IOutboxRepository=p;exports.MessagePriority=g;exports.MessageStatus=n;exports.OutboxMessageFactory=l;exports.OutboxProcessor=y;exports.OutboxService=m;

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export type { IOutboxMessage, OutboxMessageOptions, IOutboxMessageHandler, OutboxMiddleware, OutboxProcessorOptions, RetryBackoffConfig, OutboxServiceOptions, } from './outbox';
+export type { IOutboxMessage, OutboxMessageOptions, IOutboxMessageHandler, OutboxMiddleware, OutboxProcessorOptions, OutboxProcessorHooks, RetryBackoffConfig, OutboxServiceOptions, } from './outbox';
 export { MessageStatus, MessagePriority } from './outbox';
 export { IOutboxRepository, OutboxMessageFactory, OutboxProcessor, EventBusOutboxHandler, OutboxService, } from './outbox';

package/dist/index.js

@@ -1,6 +1,6 @@
-import { Logger as h } from "@vytches/ddd-logging";
-import { LibUtils as p, safeRun as l } from "@vytches/ddd-utils";
-var o = /* @__PURE__ */ ((i) => (i.PENDING = "PENDING", i.PROCESSING = "PROCESSING", i.PROCESSED = "PROCESSED", i.FAILED = "FAILED", i))(o || {}), g = /* @__PURE__ */ ((i) => (i.LOW = "low", i.NORMAL = "normal", i.HIGH = "high", i.CRITICAL = "critical", i))(g || {});
+import { Logger as u } from "@vytches/ddd-logging";
+import { LibUtils as p, safeRun as d } from "@vytches/ddd-utils";
+var n = /* @__PURE__ */ ((i) => (i.PENDING = "PENDING", i.PROCESSING = "PROCESSING", i.PROCESSED = "PROCESSED", i.FAILED = "FAILED", i))(n || {}), g = /* @__PURE__ */ ((i) => (i.LOW = "low", i.NORMAL = "normal", i.HIGH = "high", i.CRITICAL = "critical", i))(g || {});
 class m {
   /**
    * Schedules a retry for a failed message at a specific future time.
@@ -21,8 +21,29 @@ class m {
   scheduleRetry(e, t) {
     return Promise.resolve();
   }
+  /**
+   * Resets messages stuck in `PROCESSING` back to `PENDING` so they can be
+   * re-dispatched. Used for crash recovery: if a worker dies mid-batch, its
+   * in-flight messages remain `PROCESSING` forever without this.
+   *
+   * Default implementation is a no-op returning `0` — repositories that do not
+   * track a per-message "processing since" timestamp simply opt out. Override
+   * in concrete repositories, e.g.:
+   * `UPDATE outbox_messages SET status='PENDING' WHERE status='PROCESSING' AND updated_at < olderThan`.
+   *
+   * **Safety:** implementations MUST only reset messages whose processing
+   * started strictly before `olderThan`. `OutboxProcessor` always passes a past
+   * timestamp (`now - crashRecoveryThresholdMs`, with the threshold validated to
+   * be `>= messageTimeout`), so legitimately in-flight messages are never reset.
+   *
+   * @param olderThan Reset only `PROCESSING` messages last touched before this instant
+   * @returns Number of messages reset to `PENDING`
+   */
+  resetStaleProcessing(e) {
+    return Promise.resolve(0);
+  }
 }
-class c {
+class h {
   /**
    * Creates a new outbox message
    * @param messageType Type of the message
@@ -36,7 +57,7 @@ class c {
       messageType: e,
       payload: t,
       metadata: s?.metadata || {},
-      status: o.PENDING,
+      status: n.PENDING,
       attempts: 0,
       createdAt: /* @__PURE__ */ new Date(),
       priority: s?.priority || g.NORMAL
@@ -53,7 +74,7 @@ class c {
    */
   static createDelayedMessage(e, t, s, r) {
     const a = new Date(Date.now() + s);
-    return c.createMessage(e, t, {
+    return h.createMessage(e, t, {
       ...r,
       processAfter: a
     });
@@ -66,7 +87,7 @@ class c {
    * @returns High priority outbox message
    */
   static createHighPriorityMessage(e, t, s) {
-    return c.createMessage(e, t, {
+    return h.createMessage(e, t, {
       ...s,
       priority: g.HIGH
     });
@@ -84,26 +105,31 @@ class c {
         ...t?.metadata || {}
       }
     };
-    return t?.priority && (s.priority = t.priority), t?.processAfter && (s.processAfter = t.processAfter), c.createMessage(
+    return t?.priority && (s.priority = t.priority), t?.processAfter && (s.processAfter = t.processAfter), h.createMessage(
       `integration_event:${e.eventName}`,
       e.payload,
       s
     );
   }
 }
-class w {
+class v {
   constructor(e, t = {}) {
-    this.handlers = /* @__PURE__ */ new Map(), this.middlewares = [], this.isRunning = !1, this.logger = h.create("OutboxProcessor");
+    this.handlers = /* @__PURE__ */ new Map(), this.middlewares = [], this.isRunning = !1, this.logger = u.create("OutboxProcessor");
     const s = t.batchSize ?? 10;
     if (s > 1e4)
       throw new RangeError(`OutboxProcessor: batchSize must be ≤ 10,000, got ${s}`);
     if (t.retryBackoff) {
-      const { initial: r, multiplier: a, maxDelay: n } = t.retryBackoff;
-      if (r <= 0 || a <= 0 || n <= 0)
+      const { initial: o, multiplier: l, maxDelay: c } = t.retryBackoff;
+      if (o <= 0 || l <= 0 || c <= 0)
         throw new RangeError(
-          `OutboxProcessor: retryBackoff fields must be positive numbers (initial=${r}, multiplier=${a}, maxDelay=${n})`
+          `OutboxProcessor: retryBackoff fields must be positive numbers (initial=${o}, multiplier=${l}, maxDelay=${c})`
         );
     }
+    const r = t.messageTimeout ?? 3e4, a = t.crashRecoveryThresholdMs ?? Math.max(3e5, r);
+    if (a < r)
+      throw new RangeError(
+        `OutboxProcessor: crashRecoveryThresholdMs (${a}) must be ≥ messageTimeout (${r}) to avoid resetting in-flight messages`
+      );
     this.repository = e, this.options = {
       batchSize: s,
       maxRetries: t.maxRetries ?? 3,
@@ -114,11 +140,32 @@ class w {
         g.NORMAL,
         g.LOW
       ],
-      messageTimeout: t.messageTimeout ?? 3e4,
+      messageTimeout: r,
       enableLogging: t.enableLogging ?? !1,
-      retryBackoff: t.retryBackoff
+      retryBackoff: t.retryBackoff,
+      messageTypes: t.messageTypes,
+      crashRecoveryIntervalMs: t.crashRecoveryIntervalMs,
+      crashRecoveryThresholdMs: a,
+      adaptiveRepoll: t.adaptiveRepoll ?? !1,
+      adaptiveRepollMaxConsecutive: t.adaptiveRepollMaxConsecutive ?? 5,
+      adaptiveRepollPauseMs: t.adaptiveRepollPauseMs ?? 50,
+      startupJitterMs: t.startupJitterMs ?? 0,
+      hooks: t.hooks
     };
   }
+  /**
+   * Invokes an observability hook in isolation. A throwing hook is logged and
+   * swallowed so it can never break the processing loop (mitigation T3).
+   */
+  safelyInvokeHook(e, t) {
+    if (this.options.hooks)
+      try {
+        t();
+      } catch (s) {
+        const r = s instanceof Error ? s.message : String(s);
+        this.logger.error(`Outbox hook ${e} threw and was ignored: ${r}`);
+      }
+  }
   /**
    * Registers a message handler for a specific message type
    */
@@ -139,7 +186,9 @@ class w {
       this.logger.warn("Processor is already running");
       return;
     }
-    this.isRunning = !0, this.logger.info("Starting outbox processor"), this.scheduleProcessing();
+    this.isRunning = !0, this.logger.info("Starting outbox processor");
+    const e = this.options.startupJitterMs > 0 ? Math.floor(Math.random() * this.options.startupJitterMs) : 0;
+    this.scheduleProcessing(0, this.options.processingInterval + e), this.scheduleCrashRecovery();
   }
   /**
    * Stops the processor
@@ -149,7 +198,7 @@ class w {
       this.logger.warn("Processor is not running");
       return;
     }
-    this.isRunning = !1, this.processingTimer && (clearTimeout(this.processingTimer), this.processingTimer = void 0), this.logger.info("Stopped outbox processor");
+    this.isRunning = !1, this.processingTimer && (clearTimeout(this.processingTimer), this.processingTimer = void 0), this.crashRecoveryTimer && (clearTimeout(this.crashRecoveryTimer), this.crashRecoveryTimer = void 0), this.logger.info("Stopped outbox processor");
   }
   /**
    * Processes a single batch of pending messages.
@@ -172,38 +221,57 @@ class w {
    * **Quiescence:** if there are no pending messages, returns immediately
    * without invoking handlers.
    *
+   * @returns `{ processed, batchSize }` — `processed` is how many messages were
+   *   dispatched this batch, `batchSize` the configured limit. A full batch
+   *   (`processed >= batchSize`) signals a likely backlog. Callers that ignore
+   *   the return value are unaffected (the value was previously `void`).
    * @public
    * @stable
    * @since 0.1.0
    */
   async processBatch() {
+    const e = this.options.batchSize;
     if (!this.isRunning)
-      return;
-    const [e, t] = await l(
-      () => this.repository.getUnprocessedMessages(this.options.batchSize, this.options.priorityOrder)
+      return { processed: 0, batchSize: e };
+    const [t, s] = await d(
+      () => this.repository.getUnprocessedMessages(
+        e,
+        this.options.priorityOrder,
+        this.options.messageTypes
+      )
     );
-    if (e) {
-      const a = e instanceof Error ? e.message : String(e);
-      this.logger.error(`Error retrieving messages: ${a}`);
-      return;
-    }
-    const s = t;
-    if (!s || !Array.isArray(s) || s.length === 0) {
-      this.logger.debug("No pending messages to process");
-      return;
+    if (t) {
+      const c = t instanceof Error ? t.message : String(t);
+      return this.logger.error(`Error retrieving messages: ${c}`), { processed: 0, batchSize: e };
     }
-    this.logger.info(`Processing ${s.length} messages`);
-    const r = s.map((a) => this.processMessage(a));
-    await Promise.allSettled(r), this.logger.info(`Completed processing batch of ${s.length} messages`);
+    const r = s;
+    if (!r || !Array.isArray(r) || r.length === 0)
+      return this.logger.debug("No pending messages to process"), { processed: 0, batchSize: e };
+    this.logger.info(`Processing ${r.length} messages`);
+    const a = Date.now(), l = (await Promise.allSettled(
+      r.map((c) => this.processMessage(c))
+    )).filter(
+      (c) => c.status === "rejected" || c.status === "fulfilled" && c.value === !1
+    ).length;
+    return this.logger.info(`Completed processing batch of ${r.length} messages`), this.safelyInvokeHook(
+      "onBatchComplete",
+      () => this.options.hooks?.onBatchComplete?.({
+        processed: r.length,
+        failed: l,
+        batchSize: e,
+        durationMs: Date.now() - a
+      })
+    ), { processed: r.length, batchSize: e };
   }
   /**
-   * Processes a single message through the middleware pipeline
+   * Processes a single message through the middleware pipeline.
+   * @returns `true` if the message was processed successfully, `false` if it failed.
    */
   async processMessage(e) {
-    const [t] = await l(async () => {
-      await this.repository.updateStatus(e.id, o.PROCESSING), await this.buildPipeline(e)(e), await this.repository.updateStatus(e.id, o.PROCESSED), this.logger.debug(`Successfully processed message ${e.id}`);
+    const [t] = await d(async () => {
+      await this.repository.updateStatus(e.id, n.PROCESSING), await this.buildPipeline(e)(e), await this.repository.updateStatus(e.id, n.PROCESSED), this.logger.debug(`Successfully processed message ${e.id}`);
     });
-    t && await this.handleMessageError(e, t);
+    return t ? (await this.handleMessageError(e, t), !1) : !0;
   }
   /**
    * Builds the middleware pipeline for message processing
@@ -216,8 +284,8 @@ class w {
       await Promise.race([
         t.handle(r),
         new Promise(
-          (a, n) => setTimeout(
-            () => n(new Error("Message processing timeout")),
+          (a, o) => setTimeout(
+            () => o(new Error("Message processing timeout")),
             this.options.messageTimeout
           )
         )
@@ -231,27 +299,70 @@ class w {
   async handleMessageError(e, t) {
     try {
       const s = await this.repository.incrementAttempt(e.id);
-      if (this.logger.warn(`Message ${e.id} failed, attempt ${s}: ${t?.message}`), s >= this.options.maxRetries)
-        await this.repository.updateStatus(e.id, o.FAILED, t), this.logger.error(`Message ${e.id} marked as failed after ${s} attempts`);
+      if (this.logger.warn(`Message ${e.id} failed, attempt ${s}: ${t?.message}`), this.safelyInvokeHook(
+        "onMessageFailed",
+        () => this.options.hooks?.onMessageFailed?.(e, t, s)
+      ), s >= this.options.maxRetries)
+        await this.repository.updateStatus(e.id, n.FAILED, t), this.logger.error(`Message ${e.id} marked as failed after ${s} attempts`), this.safelyInvokeHook(
+          "onPermanentFailure",
+          () => this.options.hooks?.onPermanentFailure?.(e, t)
+        );
       else if (this.options.retryBackoff) {
-        const { initial: r, multiplier: a, maxDelay: n } = this.options.retryBackoff, d = Math.min(r * Math.pow(a, s - 1), n), u = new Date(Date.now() + d);
-        await this.repository.updateStatus(e.id, o.PENDING), await this.repository.scheduleRetry(e.id, u), this.logger.info(
-          `Message ${e.id} scheduled for retry in ${d}ms (attempt ${s})`
+        const { initial: r, multiplier: a, maxDelay: o } = this.options.retryBackoff, l = Math.min(r * Math.pow(a, s - 1), o), c = new Date(Date.now() + l);
+        await this.repository.updateStatus(e.id, n.PENDING), await this.repository.scheduleRetry(e.id, c), this.logger.info(
+          `Message ${e.id} scheduled for retry in ${l}ms (attempt ${s})`
         );
       } else
-        await this.repository.updateStatus(e.id, o.PENDING), this.logger.info(`Message ${e.id} scheduled for retry (attempt ${s + 1})`);
+        await this.repository.updateStatus(e.id, n.PENDING), this.logger.info(`Message ${e.id} scheduled for retry (attempt ${s + 1})`);
     } catch (s) {
       const r = s instanceof Error ? s.message : String(s);
       this.logger.error(`Error updating message status: ${r}`);
     }
   }
   /**
-   * Schedules the next processing cycle
+   * Schedules the next processing cycle.
+   *
+   * With `adaptiveRepoll` enabled, a full batch re-polls immediately (`delay 0`)
+   * to drain a backlog — until `adaptiveRepollMaxConsecutive` consecutive full
+   * batches trip the livelock guard, after which an `adaptiveRepollPauseMs`
+   * pause is inserted. Any non-full batch resets the cadence to
+   * `processingInterval`.
+   *
+   * @param consecutiveFullBatches running count of back-to-back full batches
+   * @param delay milliseconds to wait before the next batch
    */
-  scheduleProcessing() {
+  scheduleProcessing(e = 0, t = this.options.processingInterval) {
     this.isRunning && (this.processingTimer = setTimeout(async () => {
-      await this.processBatch(), this.scheduleProcessing();
-    }, this.options.processingInterval));
+      const s = await this.processBatch();
+      if (this.options.adaptiveRepoll && s.processed > 0 && s.processed >= s.batchSize) {
+        const a = e + 1, o = a > this.options.adaptiveRepollMaxConsecutive ? this.options.adaptiveRepollPauseMs : 0;
+        this.scheduleProcessing(a, o);
+      } else
+        this.scheduleProcessing(0, this.options.processingInterval);
+    }, t));
+  }
+  /**
+   * Schedules the next crash-recovery cycle. No-op unless
+   * `crashRecoveryIntervalMs` was configured.
+   */
+  scheduleCrashRecovery() {
+    !this.isRunning || this.options.crashRecoveryIntervalMs === void 0 || (this.crashRecoveryTimer = setTimeout(async () => {
+      await this.runCrashRecovery(), this.scheduleCrashRecovery();
+    }, this.options.crashRecoveryIntervalMs));
+  }
+  /**
+   * Resets messages orphaned in `PROCESSING` (older than
+   * `crashRecoveryThresholdMs`) back to `PENDING` via the repository. Errors are
+   * logged, never thrown — crash recovery must not crash the processor.
+   */
+  async runCrashRecovery() {
+    const e = new Date(Date.now() - this.options.crashRecoveryThresholdMs), [t, s] = await d(() => this.repository.resetStaleProcessing(e));
+    if (t) {
+      const r = t instanceof Error ? t.message : String(t);
+      this.logger.error(`Crash recovery failed: ${r}`);
+      return;
+    }
+    s && s > 0 && this.logger.warn(`Crash recovery reset ${s} stale PROCESSING message(s) to PENDING`);
   }
   /**
    * Logs messages if logging is enabled
@@ -289,9 +400,9 @@ class M {
     await this.eventBus.publish(s);
   }
 }
-class S {
+class R {
   constructor(e, t = {}) {
-    this.logger = h.create("OutboxService"), this.repository = e, this.options = {
+    this.logger = u.create("OutboxService"), this.repository = e, this.options = {
       defaultPriority: t.defaultPriority ?? g.NORMAL,
       defaultMetadata: t.defaultMetadata ?? {},
       autoCleanup: t.autoCleanup ?? !1,
@@ -303,7 +414,7 @@ class S {
    * Saves a message to the outbox
    */
   async saveMessage(e, t, s) {
-    const r = c.createMessage(e, t, {
+    const r = h.createMessage(e, t, {
       priority: this.options.defaultPriority,
       metadata: { ...this.options.defaultMetadata, ...s?.metadata },
       ...s
@@ -315,10 +426,10 @@ class S {
    */
   async saveMessages(e) {
     const t = e.map(
-      ({ messageType: r, payload: a, options: n }) => c.createMessage(r, a, {
+      ({ messageType: r, payload: a, options: o }) => h.createMessage(r, a, {
         priority: this.options.defaultPriority,
-        metadata: { ...this.options.defaultMetadata, ...n?.metadata },
-        ...n
+        metadata: { ...this.options.defaultMetadata, ...o?.metadata },
+        ...o
       })
     ), s = await this.repository.saveBatch(t);
     return this.logger.debug(`Saved batch of ${e.length} messages`), s;
@@ -327,14 +438,14 @@ class S {
    * Schedules a message for delayed processing
    */
   async scheduleMessage(e, t, s, r) {
-    const a = c.createDelayedMessage(e, t, s, {
+    const a = h.createDelayedMessage(e, t, s, {
       priority: this.options.defaultPriority,
       metadata: { ...this.options.defaultMetadata, ...r?.metadata },
       ...r
-    }), n = await this.repository.scheduleMessage(a, a.processAfter);
+    }), o = await this.repository.scheduleMessage(a, a.processAfter);
     return this.logger.debug(
-      `Scheduled message ${n} of type ${e} for processing in ${s}ms`
-    ), n;
+      `Scheduled message ${o} of type ${e} for processing in ${s}ms`
+    ), o;
   }
   /**
    * Saves a high priority message to the outbox
@@ -358,7 +469,7 @@ class S {
    * Converts a domain event to an outbox message and saves it
    */
   async saveDomainEvent(e, t) {
-    const s = c.createFromIntegrationEvent(
+    const s = h.createFromIntegrationEvent(
       {
         eventName: e.eventName,
         payload: e,
@@ -392,13 +503,13 @@ class S {
    * Retries a failed message by resetting it to pending status
    */
   async retryMessage(e) {
-    await this.repository.updateStatus(e, o.PENDING), this.logger.info(`Reset message ${e} to pending for retry`);
+    await this.repository.updateStatus(e, n.PENDING), this.logger.info(`Reset message ${e} to pending for retry`);
   }
   /**
    * Retries multiple failed messages
    */
   async retryMessages(e) {
-    await this.repository.updateStatusBatch(e, o.PENDING), this.logger.info(`Reset ${e.length} messages to pending for retry`);
+    await this.repository.updateStatusBatch(e, n.PENDING), this.logger.info(`Reset ${e.length} messages to pending for retry`);
   }
   /**
    * Cleans up old processed messages
@@ -408,7 +519,7 @@ class S {
     s.setDate(s.getDate() - t);
     const r = await this.repository.deleteByStatusAndAge(
       s,
-      o.PROCESSED
+      n.PROCESSED
     );
     return this.logger.info(`Cleaned up ${r} processed messages older than ${t} days`), r;
   }
@@ -418,10 +529,10 @@ class S {
   async getStats() {
     const e = this.repository;
     return e.getMessageCountByStatus ? {
-      totalPending: e.getMessageCountByStatus(o.PENDING),
-      totalProcessing: e.getMessageCountByStatus(o.PROCESSING),
-      totalProcessed: e.getMessageCountByStatus(o.PROCESSED),
-      totalFailed: e.getMessageCountByStatus(o.FAILED)
+      totalPending: e.getMessageCountByStatus(n.PENDING),
+      totalProcessing: e.getMessageCountByStatus(n.PROCESSING),
+      totalProcessed: e.getMessageCountByStatus(n.PROCESSED),
+      totalFailed: e.getMessageCountByStatus(n.FAILED)
     } : {
       totalPending: (await this.repository.getUnprocessedMessages(1e3)).length,
       totalProcessing: 0,
@@ -443,8 +554,8 @@ export {
   M as EventBusOutboxHandler,
   m as IOutboxRepository,
   g as MessagePriority,
-  o as MessageStatus,
-  c as OutboxMessageFactory,
-  w as OutboxProcessor,
-  S as OutboxService
+  n as MessageStatus,
+  h as OutboxMessageFactory,
+  v as OutboxProcessor,
+  R as OutboxService
 };

package/dist/outbox/index.d.ts

@@ -2,4 +2,5 @@ export * from './outbox-interfaces';
 export * from './outbox-repository.interface';
 export * from './outbox-message-factory';
 export * from './outbox-processor';
+export * from './outbox-hooks';
 export * from './outbox-service';

package/dist/outbox/outbox-hooks.d.ts

@@ -0,0 +1,24 @@
+import { IOutboxMessage } from './outbox-interfaces';
+/**
+ * Observability callbacks for {@link OutboxProcessor}. Use them to wire metrics
+ * (Prometheus counters, DataDog), alerting on permanent failures, or dead-letter
+ * routing — without coupling the processor to any specific telemetry stack.
+ *
+ * **Hooks must be synchronous and fast.** Each call is wrapped in a try/catch by
+ * the processor, so a throwing hook is logged and ignored (it never breaks the
+ * processing loop), but a slow hook still blocks the batch. Offload heavy work
+ * (network, disk) to a queue inside the hook.
+ */
+export interface OutboxProcessorHooks {
+    /** Fired once per processed batch with aggregate counts and wall-clock duration. */
+    onBatchComplete?(result: {
+        processed: number;
+        failed: number;
+        batchSize: number;
+        durationMs: number;
+    }): void;
+    /** Fired on every message failure, including ones that will be retried. */
+    onMessageFailed?(message: IOutboxMessage, error: Error, attempt: number): void;
+    /** Fired when a message is marked `FAILED` after exhausting `maxRetries`. */
+    onPermanentFailure?(message: IOutboxMessage, error: Error): void;
+}

package/dist/outbox/outbox-processor.d.ts

@@ -1,6 +1,7 @@
 import { IEventBus } from '../../../contracts/src/index.ts';
 import { IOutboxMessage, IOutboxMessageHandler, OutboxMiddleware, MessagePriority } from './outbox-interfaces';
 import { IOutboxRepository } from './outbox-repository.interface';
+import { OutboxProcessorHooks } from './outbox-hooks';
 export interface RetryBackoffConfig {
     /** Initial delay in milliseconds before first retry (default: 1000) */
     initial: number;
@@ -31,6 +32,54 @@ export interface OutboxProcessorOptions {
      * If omitted, immediate retry is used for all messages.
      */
     retryBackoff?: RetryBackoffConfig;
+    /**
+     * Optional allow-list of message types to process. When set, only messages
+     * of these types are fetched from the repository (passed through to
+     * `getUnprocessedMessages`). Lets multiple processors partition the outbox
+     * by type. Omit to process all types.
+     */
+    messageTypes?: string[];
+    /**
+     * When set, the processor periodically calls
+     * `IOutboxRepository.resetStaleProcessing()` every N ms to recover messages
+     * orphaned in `PROCESSING` by a crashed worker. Omit to disable crash recovery.
+     */
+    crashRecoveryIntervalMs?: number;
+    /**
+     * How old (in ms) a `PROCESSING` message must be before crash recovery resets
+     * it to `PENDING`. Must be `>= messageTimeout` so legitimately in-flight
+     * messages are never reset. Defaults to `max(300_000, messageTimeout)`.
+     * Setting this below `messageTimeout` throws a `RangeError` from the constructor.
+     */
+    crashRecoveryThresholdMs?: number;
+    /**
+     * When `true`, after a **full** batch (every fetched slot used) the processor
+     * re-polls immediately instead of waiting `processingInterval`, draining a
+     * backlog faster. Defaults to `false` (opt-in — no behavior change).
+     */
+    adaptiveRepoll?: boolean;
+    /**
+     * Livelock guard for `adaptiveRepoll`: after this many consecutive full
+     * batches the processor inserts an `adaptiveRepollPauseMs` pause instead of
+     * re-polling immediately, yielding the event loop. Defaults to `5`.
+     */
+    adaptiveRepollMaxConsecutive?: number;
+    /**
+     * Pause (ms) inserted once the `adaptiveRepollMaxConsecutive` guard trips.
+     * Defaults to `50`.
+     */
+    adaptiveRepollPauseMs?: number;
+    /**
+     * Random delay (0..N ms) added before the first poll on `start()`, to
+     * de-synchronize many processors that boot simultaneously. Defaults to `0`.
+     */
+    startupJitterMs?: number;
+    /**
+     * Observability callbacks (batch completion, message failure, permanent
+     * failure). Each invocation is isolated in a try/catch — a throwing hook is
+     * logged and never breaks the processing loop. Omit to disable.
+     */
+    hooks?: OutboxProcessorHooks;
 }
 export declare class OutboxProcessor {
     private readonly repository;
@@ -39,8 +88,14 @@ export declare class OutboxProcessor {
     private readonly middlewares;
     private isRunning;
     private processingTimer?;
+    private crashRecoveryTimer?;
     private readonly logger;
     constructor(repository: IOutboxRepository, options?: OutboxProcessorOptions);
+    /**
+     * Invokes an observability hook in isolation. A throwing hook is logged and
+     * swallowed so it can never break the processing loop (mitigation T3).
+     */
+    private safelyInvokeHook;
     /**
      * Registers a message handler for a specific message type
      */
@@ -78,13 +133,21 @@ export declare class OutboxProcessor {
      * **Quiescence:** if there are no pending messages, returns immediately
      * without invoking handlers.
      *
+     * @returns `{ processed, batchSize }` — `processed` is how many messages were
+     *   dispatched this batch, `batchSize` the configured limit. A full batch
+     *   (`processed >= batchSize`) signals a likely backlog. Callers that ignore
+     *   the return value are unaffected (the value was previously `void`).
      * @public
      * @stable
      * @since 0.1.0
      */
-    processBatch(): Promise<void>;
+    processBatch(): Promise<{
+        processed: number;
+        batchSize: number;
+    }>;
     /**
-     * Processes a single message through the middleware pipeline
+     * Processes a single message through the middleware pipeline.
+     * @returns `true` if the message was processed successfully, `false` if it failed.
      */
     private processMessage;
     /**
@@ -96,9 +159,29 @@ export declare class OutboxProcessor {
      */
     private handleMessageError;
     /**
-     * Schedules the next processing cycle
+     * Schedules the next processing cycle.
+     *
+     * With `adaptiveRepoll` enabled, a full batch re-polls immediately (`delay 0`)
+     * to drain a backlog — until `adaptiveRepollMaxConsecutive` consecutive full
+     * batches trip the livelock guard, after which an `adaptiveRepollPauseMs`
+     * pause is inserted. Any non-full batch resets the cadence to
+     * `processingInterval`.
+     *
+     * @param consecutiveFullBatches running count of back-to-back full batches
+     * @param delay milliseconds to wait before the next batch
      */
     private scheduleProcessing;
+    /**
+     * Schedules the next crash-recovery cycle. No-op unless
+     * `crashRecoveryIntervalMs` was configured.
+     */
+    private scheduleCrashRecovery;
+    /**
+     * Resets messages orphaned in `PROCESSING` (older than
+     * `crashRecoveryThresholdMs`) back to `PENDING` via the repository. Errors are
+     * logged, never thrown — crash recovery must not crash the processor.
+     */
+    private runCrashRecovery;
     /**
      * Logs messages if logging is enabled
      */

package/dist/outbox/outbox-repository.interface.d.ts

@@ -16,9 +16,13 @@ export declare abstract class IOutboxRepository {
      * Gets unprocessed messages from the outbox
      * @param limit Maximum number of messages to retrieve
      * @param priorityOrder Order of priority for processing (default: [CRITICAL, HIGH, NORMAL, LOW])
+     * @param messageTypes Optional allow-list of message types to fetch. When
+     *   provided, only messages whose `messageType` is in this list are returned
+     *   (e.g. `WHERE message_type IN (...)`). Omitting it fetches all types —
+     *   this parameter is optional and backward-compatible.
      * @returns Unprocessed messages
      */
-    abstract getUnprocessedMessages(limit?: number, priorityOrder?: MessagePriority[]): Promise<IOutboxMessage[]>;
+    abstract getUnprocessedMessages(limit?: number, priorityOrder?: MessagePriority[], messageTypes?: string[]): Promise<IOutboxMessage[]>;
     /**
      * Gets specific message by ID
      * @param id Message ID
@@ -75,4 +79,23 @@ export declare abstract class IOutboxRepository {
      * @param processAfter When to retry the message
      */
     scheduleRetry(_id: string, _processAfter: Date): Promise<void>;
+    /**
+     * Resets messages stuck in `PROCESSING` back to `PENDING` so they can be
+     * re-dispatched. Used for crash recovery: if a worker dies mid-batch, its
+     * in-flight messages remain `PROCESSING` forever without this.
+     *
+     * Default implementation is a no-op returning `0` — repositories that do not
+     * track a per-message "processing since" timestamp simply opt out. Override
+     * in concrete repositories, e.g.:
+     * `UPDATE outbox_messages SET status='PENDING' WHERE status='PROCESSING' AND updated_at < olderThan`.
+     *
+     * **Safety:** implementations MUST only reset messages whose processing
+     * started strictly before `olderThan`. `OutboxProcessor` always passes a past
+     * timestamp (`now - crashRecoveryThresholdMs`, with the threshold validated to
+     * be `>= messageTimeout`), so legitimately in-flight messages are never reset.
+     *
+     * @param olderThan Reset only `PROCESSING` messages last touched before this instant
+     * @returns Number of messages reset to `PENDING`
+     */
+    resetStaleProcessing(_olderThan: Date): Promise<number>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vytches/ddd-messaging",
-  "version": "0.28.0",
+  "version": "0.29.2",
   "description": "Outbox pattern and reliable message delivery",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -36,8 +36,7 @@
     "typescript": "^5.0.0",
     "vite": "^7.3.2",
     "vite-plugin-dts": "^4.0.0",
-    "vitest": "^4.0.0",
-    "@vytches/ddd-testing": "0.28.0"
+    "vitest": "^4.0.0"
   },
   "nx": {
     "tags": [
@@ -51,7 +50,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@vytches/ddd-events": "0.28.0"
+    "@vytches/ddd-events": "0.29.2"
   },
   "scripts": {
     "build": "vite build",