@vytches/ddd-messaging 0.30.0 → 0.31.0

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 n=(i=>(i.PENDING="PENDING",i.PROCESSING="PROCESSING",i.PROCESSED="PROCESSED",i.FAILED="FAILED",i))(n||{}),l=(i=>(i.LOW="low",i.NORMAL="normal",i.HIGH="high",i.CRITICAL="critical",i))(l||{});const p=["critical","high","normal","low"];function y(i,e,t=p){const s=t.includes(i)?t.indexOf(i):t.length,r=t.includes(e)?t.indexOf(e):t.length;return s-r}class f{scheduleRetry(e,t){return Promise.resolve()}resetStaleProcessing(e){return Promise.resolve(0)}}class g{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||l.NORMAL};return s?.processAfter&&(r.processAfter=s.processAfter),r}static createDelayedMessage(e,t,s,r){const a=new Date(Date.now()+s);return g.createMessage(e,t,{...r,processAfter:a})}static createHighPriorityMessage(e,t,s){return g.createMessage(e,t,{...s,priority:l.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),g.createMessage(`integration_event:${e.eventName}`,e.payload,s)}}class m{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??[l.CRITICAL,l.HIGH,l.NORMAL,l.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}`)}registerDefaultHandler(e){this.defaultHandler=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)??this.defaultHandler;if(!t)throw new Error(`No handler registered for message type: ${e.messageType}`);this.handlers.has(e.messageType)||this.logger.debug(`Default handler used 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,hasDefaultHandler:this.defaultHandler!==void 0}}}class v{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??l.NORMAL,defaultMetadata:t.defaultMetadata??{},autoCleanup:t.autoCleanup??!1,cleanupAfterDays:t.cleanupAfterDays??7,enableLogging:t.enableLogging??!1}}async saveMessage(e,t,s){const r=g.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})=>g.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=g.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:l.HIGH})}async saveCriticalMessage(e,t,s){return this.saveMessage(e,t,{...s,priority:l.CRITICAL})}async saveDomainEvent(e,t){const s=g.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=v;exports.IOutboxRepository=f;exports.MessagePriority=l;exports.MessageStatus=n;exports.OutboxMessageFactory=g;exports.OutboxProcessor=m;exports.OutboxService=M;exports.comparePriority=y;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const p=require("@vytches/ddd-utils"),c=require("@vytches/ddd-contracts/internal");var n=(i=>(i.PENDING="PENDING",i.PROCESSING="PROCESSING",i.PROCESSED="PROCESSED",i.FAILED="FAILED",i))(n||{}),l=(i=>(i.LOW="low",i.NORMAL="normal",i.HIGH="high",i.CRITICAL="critical",i))(l||{});const m=["critical","high","normal","low"];function f(i,e,t=m){const s=t.includes(i)?t.indexOf(i):t.length,a=t.includes(e)?t.indexOf(e):t.length;return s-a}class v{async claimBatch(e,t,s){const a=await this.getUnprocessedMessages(e,t,s);return a.length===0?a:(await this.updateStatusBatch(a.map(r=>r.id),n.PROCESSING),a.map(r=>({...r,status:n.PROCESSING})))}scheduleRetry(e,t){return Promise.resolve()}resetStaleProcessing(e){return Promise.resolve(0)}}class h{static createMessage(e,t,s){const a={id:p.LibUtils.getUUID(),messageType:e,payload:t,metadata:s?.metadata||{},status:n.PENDING,attempts:0,createdAt:new Date,priority:s?.priority||l.NORMAL};return s?.processAfter&&(a.processAfter=s.processAfter),a}static createDelayedMessage(e,t,s,a){const r=new Date(Date.now()+s);return h.createMessage(e,t,{...a,processAfter:r})}static createHighPriorityMessage(e,t,s){return h.createMessage(e,t,{...s,priority:l.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),h.createMessage(`integration_event:${e.eventName}`,e.payload,s)}}class M{constructor(e,t={}){this.handlers=new Map,this.middlewares=[],this.isRunning=!1,this.warnedMissingClaimBatch=!1;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:u,maxDelay:d}=t.retryBackoff;if(o<=0||u<=0||d<=0)throw new RangeError(`OutboxProcessor: retryBackoff fields must be positive numbers (initial=${o}, multiplier=${u}, maxDelay=${d})`)}const a=t.messageTimeout??3e4,r=t.crashRecoveryThresholdMs??Math.max(3e5,a);if(r<a)throw new RangeError(`OutboxProcessor: crashRecoveryThresholdMs (${r}) must be ≥ messageTimeout (${a}) to avoid resetting in-flight messages`);this.repository=e,this.options={batchSize:s,maxRetries:t.maxRetries??3,processingInterval:t.processingInterval??5e3,priorityOrder:t.priorityOrder??[l.CRITICAL,l.HIGH,l.NORMAL,l.LOW],messageTimeout:a,enableLogging:t.enableLogging??!1,retryBackoff:t.retryBackoff,messageTypes:t.messageTypes,crashRecoveryIntervalMs:t.crashRecoveryIntervalMs,crashRecoveryThresholdMs:r,adaptiveRepoll:t.adaptiveRepoll??!1,adaptiveRepollMaxConsecutive:t.adaptiveRepollMaxConsecutive??5,adaptiveRepollPauseMs:t.adaptiveRepollPauseMs??50,startupJitterMs:t.startupJitterMs??0,hooks:t.hooks,useClaimBatch:t.useClaimBatch??!1}}safelyInvokeHook(e,t){if(this.options.hooks)try{t()}catch(s){c.internalLogger.error(`OutboxProcessor: hook ${e} threw and was ignored`,s instanceof Error?s:void 0,{hookName:e})}}registerHandler(e,t){this.handlers.set(e,t)}registerDefaultHandler(e){this.defaultHandler&&c.internalLogger.warn("registerDefaultHandler: replacing existing default handler — previous handler discarded"),this.defaultHandler=e}use(e){this.middlewares.push(e)}start(){if(this.isRunning){c.internalLogger.warn("OutboxProcessor: processor is already running");return}this.isRunning=!0;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){c.internalLogger.warn("OutboxProcessor: 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)}async processBatch(){const e=this.options.batchSize;if(!this.isRunning)return{processed:0,batchSize:e};const t=this.repository.claimBatch,s=this.options.useClaimBatch===!0&&typeof t=="function";this.options.useClaimBatch&&!s&&!this.warnedMissingClaimBatch&&(this.warnedMissingClaimBatch=!0,c.internalLogger.warn("OutboxProcessor: useClaimBatch is enabled but the repository does not implement claimBatch() — falling back to getUnprocessedMessages (no atomic-claim protection)"));const[a,r]=await p.safeRun(()=>s&&t?t.call(this.repository,e,this.options.priorityOrder,this.options.messageTypes):this.repository.getUnprocessedMessages(e,this.options.priorityOrder,this.options.messageTypes));if(a)return c.internalLogger.error("OutboxProcessor: error retrieving messages",a instanceof Error?a:void 0),{processed:0,batchSize:e};const o=r;if(!o||!Array.isArray(o)||o.length===0)return{processed:0,batchSize:e};const u=Date.now(),y=(await Promise.allSettled(o.map(g=>this.processMessage(g,s)))).filter(g=>g.status==="rejected"||g.status==="fulfilled"&&g.value===!1).length;return this.safelyInvokeHook("onBatchComplete",()=>this.options.hooks?.onBatchComplete?.({processed:o.length,failed:y,batchSize:e,durationMs:Date.now()-u})),{processed:o.length,batchSize:e}}async processMessage(e,t=!1){const[s]=await p.safeRun(async()=>{t||await this.repository.updateStatus(e.id,n.PROCESSING),await this.buildPipeline(e)(e),await this.repository.updateStatus(e.id,n.PROCESSED)});return s?(await this.handleMessageError(e,s),!1):!0}buildPipeline(e){const t=this.handlers.get(e.messageType)??this.defaultHandler;if(!t)throw new Error(`No handler registered for message type: ${e.messageType}`);const s=async a=>{let r;try{await Promise.race([t.handle(a),new Promise((o,u)=>{r=setTimeout(()=>u(new Error("Message processing timeout")),this.options.messageTimeout)})])}finally{r!==void 0&&clearTimeout(r)}};return this.middlewares.reduceRight((a,r)=>r(a),s)}async handleMessageError(e,t){try{const s=await this.repository.incrementAttempt(e.id);if(c.internalLogger.warn(`OutboxProcessor: message ${e.id} failed, attempt ${s}: ${p.LibUtils.sanitizeLogMessage(t?.message??String(t))}`),this.safelyInvokeHook("onMessageFailed",()=>this.options.hooks?.onMessageFailed?.(e,t,s)),s>=this.options.maxRetries)await this.repository.updateStatus(e.id,n.FAILED,t),c.internalLogger.error("OutboxProcessor: message permanently failed",t,{messageId:e.id,attempts:s}),this.safelyInvokeHook("onPermanentFailure",()=>this.options.hooks?.onPermanentFailure?.(e,t));else if(this.options.retryBackoff){const{initial:a,multiplier:r,maxDelay:o}=this.options.retryBackoff,u=Math.min(a*Math.pow(r,s-1),o),d=new Date(Date.now()+u);await this.repository.updateStatus(e.id,n.PENDING),await this.repository.scheduleRetry(e.id,d)}else await this.repository.updateStatus(e.id,n.PENDING)}catch(s){c.internalLogger.error("OutboxProcessor: error updating message status",s instanceof Error?s:void 0,{messageId:e.id})}}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 r=e+1,o=r>this.options.adaptiveRepollMaxConsecutive?this.options.adaptiveRepollPauseMs:0;this.scheduleProcessing(r,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 p.safeRun(()=>this.repository.resetStaleProcessing(e));if(t){c.internalLogger.error("OutboxProcessor: crash recovery failed",t instanceof Error?t:void 0);return}s&&s>0&&c.internalLogger.warn(`OutboxProcessor: crash recovery reset ${s} stale PROCESSING message(s) to PENDING`)}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,hasDefaultHandler:this.defaultHandler!==void 0}}}class R{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 P{constructor(e,t={}){this.repository=e,this.options={defaultPriority:t.defaultPriority??l.NORMAL,defaultMetadata:t.defaultMetadata??{},autoCleanup:t.autoCleanup??!1,cleanupAfterDays:t.cleanupAfterDays??7,enableLogging:t.enableLogging??!1}}async saveMessage(e,t,s){const a=h.createMessage(e,t,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...s?.metadata},...s});return await this.repository.saveMessage(a)}async saveMessages(e){const t=e.map(({messageType:a,payload:r,options:o})=>h.createMessage(a,r,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...o?.metadata},...o}));return await this.repository.saveBatch(t)}async scheduleMessage(e,t,s,a){const r=h.createDelayedMessage(e,t,s,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...a?.metadata},...a});return await this.repository.scheduleMessage(r,r.processAfter)}async saveHighPriorityMessage(e,t,s){return this.saveMessage(e,t,{...s,priority:l.HIGH})}async saveCriticalMessage(e,t,s){return this.saveMessage(e,t,{...s,priority:l.CRITICAL})}async saveDomainEvent(e,t){const s=h.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});return await this.repository.saveMessage(s)}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)}async retryMessages(e){await this.repository.updateStatusBatch(e,n.PENDING)}async cleanup(e){const t=e??this.options.cleanupAfterDays,s=new Date;return s.setDate(s.getDate()-t),await this.repository.deleteByStatusAndAge(s,n.PROCESSED)}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}}}exports.EventBusOutboxHandler=R;exports.IOutboxRepository=v;exports.MessagePriority=l;exports.MessageStatus=n;exports.OutboxMessageFactory=h;exports.OutboxProcessor=M;exports.OutboxService=P;exports.comparePriority=f;

package/dist/index.js

@@ -1,18 +1,59 @@
-import { Logger as u } from "@vytches/ddd-logging";
-import { LibUtils as p, safeRun as d } from "@vytches/ddd-utils";
+import { LibUtils as y, safeRun as g } from "@vytches/ddd-utils";
+import { internalLogger as c } from "@vytches/ddd-contracts/internal";
 var n = /* @__PURE__ */ ((i) => (i.PENDING = "PENDING", i.PROCESSING = "PROCESSING", i.PROCESSED = "PROCESSED", i.FAILED = "FAILED", i))(n || {}), l = /* @__PURE__ */ ((i) => (i.LOW = "low", i.NORMAL = "normal", i.HIGH = "high", i.CRITICAL = "critical", i))(l || {});
-const y = [
+const f = [
   "critical",
   "high",
   "normal",
   "low"
   /* LOW */
 ];
-function v(i, e, t = y) {
-  const s = t.includes(i) ? t.indexOf(i) : t.length, r = t.includes(e) ? t.indexOf(e) : t.length;
-  return s - r;
+function R(i, e, t = f) {
+  const s = t.includes(i) ? t.indexOf(i) : t.length, a = t.includes(e) ? t.indexOf(e) : t.length;
+  return s - a;
 }
-class M {
+class w {
+  /**
+   * Atomically claims a batch of unprocessed messages: reads PENDING
+   * messages *and* marks them `PROCESSING` in the same operation, so two
+   * concurrent callers (two processor instances, or two racing calls on one
+   * instance) never both receive the same message.
+   *
+   * **Optional, and non-atomic by default.** This method is declared with
+   * `?` — it is NOT part of the required abstract contract, so existing
+   * `IOutboxRepository` subclasses keep compiling unmodified (AC#5). The
+   * default implementation provided here is a convenience shim only: it
+   * calls {@link getUnprocessedMessages} and then `updateStatusBatch(...,
+   * PROCESSING)` as two separate steps. **That is NOT atomic** — it has the
+   * exact same read-then-mark race window as calling
+   * `getUnprocessedMessages` + `updateStatus` manually, and is safe only for
+   * a single-worker deployment. Override `claimBatch` in a concrete
+   * repository (e.g. backed by `SELECT ... FOR UPDATE SKIP LOCKED`, or a
+   * single atomic `UPDATE ... WHERE status='PENDING' LIMIT n RETURNING *`)
+   * to get real multi-worker/multi-processor safety.
+   *
+   * `OutboxProcessor` only calls this method when
+   * `OutboxProcessorOptions.useClaimBatch` is explicitly set to `true`
+   * (opt-in, default `false`) — see AC#1/AC#2. When enabled, the processor
+   * skips its own redundant `updateStatus(id, PROCESSING)` call for messages
+   * returned by `claimBatch`, since claiming already performed that mark.
+   *
+   * Handlers should be idempotent to side effects regardless — transient
+   * failures or duplicate-claim races (e.g. with the non-atomic default
+   * implementation) may still cause a handler to run more than once.
+   *
+   * @param limit - Maximum number of messages to claim.
+   * @param priorityOrder - See {@link getUnprocessedMessages}.
+   * @param messageTypes - See {@link getUnprocessedMessages}.
+   * @returns Messages that were claimed (already marked `PROCESSING`).
+   */
+  async claimBatch(e, t, s) {
+    const a = await this.getUnprocessedMessages(e, t, s);
+    return a.length === 0 ? a : (await this.updateStatusBatch(
+      a.map((r) => r.id),
+      n.PROCESSING
+    ), a.map((r) => ({ ...r, status: n.PROCESSING })));
+  }
   /**
    * Schedules a retry for a failed message at a specific future time.
    *
@@ -54,7 +95,7 @@ class M {
     return Promise.resolve(0);
   }
 }
-class h {
+class d {
   /**
    * Creates a new outbox message
    * @param messageType Type of the message
@@ -63,8 +104,8 @@ class h {
    * @returns Outbox message
    */
   static createMessage(e, t, s) {
-    const r = {
-      id: p.getUUID(),
+    const a = {
+      id: y.getUUID(),
       messageType: e,
       payload: t,
       metadata: s?.metadata || {},
@@ -73,7 +114,7 @@ class h {
       createdAt: /* @__PURE__ */ new Date(),
       priority: s?.priority || l.NORMAL
     };
-    return s?.processAfter && (r.processAfter = s.processAfter), r;
+    return s?.processAfter && (a.processAfter = s.processAfter), a;
   }
   /**
    * Creates a delayed outbox message
@@ -83,11 +124,11 @@ class h {
    * @param options Additional options
    * @returns Outbox message scheduled for later processing
    */
-  static createDelayedMessage(e, t, s, r) {
-    const a = new Date(Date.now() + s);
-    return h.createMessage(e, t, {
-      ...r,
-      processAfter: a
+  static createDelayedMessage(e, t, s, a) {
+    const r = new Date(Date.now() + s);
+    return d.createMessage(e, t, {
+      ...a,
+      processAfter: r
     });
   }
   /**
@@ -98,7 +139,7 @@ class h {
    * @returns High priority outbox message
    */
   static createHighPriorityMessage(e, t, s) {
-    return h.createMessage(e, t, {
+    return d.createMessage(e, t, {
       ...s,
       priority: l.HIGH
     });
@@ -116,30 +157,30 @@ class h {
         ...t?.metadata || {}
       }
     };
-    return t?.priority && (s.priority = t.priority), t?.processAfter && (s.processAfter = t.processAfter), h.createMessage(
+    return t?.priority && (s.priority = t.priority), t?.processAfter && (s.processAfter = t.processAfter), d.createMessage(
       `integration_event:${e.eventName}`,
       e.payload,
       s
     );
   }
 }
-class R {
+class P {
   constructor(e, t = {}) {
-    this.handlers = /* @__PURE__ */ new Map(), this.middlewares = [], this.isRunning = !1, this.logger = u.create("OutboxProcessor");
+    this.handlers = /* @__PURE__ */ new Map(), this.middlewares = [], this.isRunning = !1, this.warnedMissingClaimBatch = !1;
     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: g, maxDelay: c } = t.retryBackoff;
-      if (o <= 0 || g <= 0 || c <= 0)
+      const { initial: o, multiplier: h, maxDelay: u } = t.retryBackoff;
+      if (o <= 0 || h <= 0 || u <= 0)
         throw new RangeError(
-          `OutboxProcessor: retryBackoff fields must be positive numbers (initial=${o}, multiplier=${g}, maxDelay=${c})`
+          `OutboxProcessor: retryBackoff fields must be positive numbers (initial=${o}, multiplier=${h}, maxDelay=${u})`
         );
     }
-    const r = t.messageTimeout ?? 3e4, a = t.crashRecoveryThresholdMs ?? Math.max(3e5, r);
-    if (a < r)
+    const a = t.messageTimeout ?? 3e4, r = t.crashRecoveryThresholdMs ?? Math.max(3e5, a);
+    if (r < a)
       throw new RangeError(
-        `OutboxProcessor: crashRecoveryThresholdMs (${a}) must be ≥ messageTimeout (${r}) to avoid resetting in-flight messages`
+        `OutboxProcessor: crashRecoveryThresholdMs (${r}) must be ≥ messageTimeout (${a}) to avoid resetting in-flight messages`
       );
     this.repository = e, this.options = {
       batchSize: s,
@@ -151,17 +192,18 @@ class R {
         l.NORMAL,
         l.LOW
       ],
-      messageTimeout: r,
+      messageTimeout: a,
       enableLogging: t.enableLogging ?? !1,
       retryBackoff: t.retryBackoff,
       messageTypes: t.messageTypes,
       crashRecoveryIntervalMs: t.crashRecoveryIntervalMs,
-      crashRecoveryThresholdMs: a,
+      crashRecoveryThresholdMs: r,
       adaptiveRepoll: t.adaptiveRepoll ?? !1,
       adaptiveRepollMaxConsecutive: t.adaptiveRepollMaxConsecutive ?? 5,
       adaptiveRepollPauseMs: t.adaptiveRepollPauseMs ?? 50,
       startupJitterMs: t.startupJitterMs ?? 0,
-      hooks: t.hooks
+      hooks: t.hooks,
+      useClaimBatch: t.useClaimBatch ?? !1
     };
   }
   /**
@@ -173,15 +215,18 @@ class R {
       try {
         t();
       } catch (s) {
-        const r = s instanceof Error ? s.message : String(s);
-        this.logger.error(`Outbox hook ${e} threw and was ignored: ${r}`);
+        c.error(
+          `OutboxProcessor: hook ${e} threw and was ignored`,
+          s instanceof Error ? s : void 0,
+          { hookName: e }
+        );
       }
   }
   /**
    * Registers a message handler for a specific message type
    */
   registerHandler(e, t) {
-    this.handlers.set(e, t), this.logger.debug(`Registered handler for message type: ${e}`);
+    this.handlers.set(e, t);
   }
   /**
    * Registers a catch-all handler invoked when no type-specific handler matches.
@@ -196,27 +241,28 @@ class R {
    * only types that pass through that filter. To handle all types, leave
    * `messageTypes` unset.
    *
-   * Calling this method a second time silently replaces the previous default
-   * handler (idempotent).
+   * Second/subsequent call emits a warning and replaces the previous handler.
    */
   registerDefaultHandler(e) {
-    this.defaultHandler = e;
+    this.defaultHandler && c.warn(
+      "registerDefaultHandler: replacing existing default handler — previous handler discarded"
+    ), this.defaultHandler = e;
   }
   /**
    * Registers middleware for message processing pipeline
    */
   use(e) {
-    this.middlewares.push(e), this.logger.debug("Registered middleware");
+    this.middlewares.push(e);
   }
   /**
    * Starts the processor with automatic interval processing
    */
   start() {
     if (this.isRunning) {
-      this.logger.warn("Processor is already running");
+      c.warn("OutboxProcessor: processor is already running");
       return;
     }
-    this.isRunning = !0, this.logger.info("Starting outbox processor");
+    this.isRunning = !0;
     const e = this.options.startupJitterMs > 0 ? Math.floor(Math.random() * this.options.startupJitterMs) : 0;
     this.scheduleProcessing(0, this.options.processingInterval + e), this.scheduleCrashRecovery();
   }
@@ -225,10 +271,10 @@ class R {
    */
   stop() {
     if (!this.isRunning) {
-      this.logger.warn("Processor is not running");
+      c.warn("OutboxProcessor: 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");
+    this.isRunning = !1, this.processingTimer && (clearTimeout(this.processingTimer), this.processingTimer = void 0), this.crashRecoveryTimer && (clearTimeout(this.crashRecoveryTimer), this.crashRecoveryTimer = void 0);
   }
   /**
    * Processes a single batch of pending messages.
@@ -263,45 +309,57 @@ class R {
     const e = this.options.batchSize;
     if (!this.isRunning)
       return { processed: 0, batchSize: e };
-    const [t, s] = await d(
-      () => this.repository.getUnprocessedMessages(
+    const t = this.repository.claimBatch, s = this.options.useClaimBatch === !0 && typeof t == "function";
+    this.options.useClaimBatch && !s && !this.warnedMissingClaimBatch && (this.warnedMissingClaimBatch = !0, c.warn(
+      "OutboxProcessor: useClaimBatch is enabled but the repository does not implement claimBatch() — falling back to getUnprocessedMessages (no atomic-claim protection)"
+    ));
+    const [a, r] = await g(
+      () => s && t ? t.call(
+        this.repository,
+        e,
+        this.options.priorityOrder,
+        this.options.messageTypes
+      ) : 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(), g = (await Promise.allSettled(
-      r.map((c) => this.processMessage(c))
+    if (a)
+      return c.error(
+        "OutboxProcessor: error retrieving messages",
+        a instanceof Error ? a : void 0
+      ), { processed: 0, batchSize: e };
+    const o = r;
+    if (!o || !Array.isArray(o) || o.length === 0)
+      return { processed: 0, batchSize: e };
+    const h = Date.now(), m = (await Promise.allSettled(
+      o.map((p) => this.processMessage(p, s))
     )).filter(
-      (c) => c.status === "rejected" || c.status === "fulfilled" && c.value === !1
+      (p) => p.status === "rejected" || p.status === "fulfilled" && p.value === !1
     ).length;
-    return this.logger.info(`Completed processing batch of ${r.length} messages`), this.safelyInvokeHook(
+    return this.safelyInvokeHook(
       "onBatchComplete",
       () => this.options.hooks?.onBatchComplete?.({
-        processed: r.length,
-        failed: g,
+        processed: o.length,
+        failed: m,
         batchSize: e,
-        durationMs: Date.now() - a
+        durationMs: Date.now() - h
       })
-    ), { processed: r.length, batchSize: e };
+    ), { processed: o.length, batchSize: e };
   }
   /**
    * Processes a single message through the middleware pipeline.
+   * @param alreadyClaimed When `true`, the message was already marked
+   *   `PROCESSING` by `IOutboxRepository.claimBatch()` — the redundant
+   *   `updateStatus(id, PROCESSING)` call is skipped.
    * @returns `true` if the message was processed successfully, `false` if it failed.
    */
-  async processMessage(e) {
-    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}`);
+  async processMessage(e, t = !1) {
+    const [s] = await g(async () => {
+      t || await this.repository.updateStatus(e.id, n.PROCESSING), await this.buildPipeline(e)(e), await this.repository.updateStatus(e.id, n.PROCESSED);
     });
-    return t ? (await this.handleMessageError(e, t), !1) : !0;
+    return s ? (await this.handleMessageError(e, s), !1) : !0;
   }
   /**
    * Builds the middleware pipeline for message processing
@@ -310,19 +368,23 @@ class R {
     const t = this.handlers.get(e.messageType) ?? this.defaultHandler;
     if (!t)
       throw new Error(`No handler registered for message type: ${e.messageType}`);
-    this.handlers.has(e.messageType) || this.logger.debug(`Default handler used 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
-          )
-        )
-      ]);
+    const s = async (a) => {
+      let r;
+      try {
+        await Promise.race([
+          t.handle(a),
+          new Promise((o, h) => {
+            r = setTimeout(
+              () => h(new Error("Message processing timeout")),
+              this.options.messageTimeout
+            );
+          })
+        ]);
+      } finally {
+        r !== void 0 && clearTimeout(r);
+      }
     };
-    return this.middlewares.reduceRight((r, a) => a(r), s);
+    return this.middlewares.reduceRight((a, r) => r(a), s);
   }
   /**
    * Handles errors during message processing
@@ -330,24 +392,30 @@ class R {
   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(
+      if (c.warn(
+        `OutboxProcessor: message ${e.id} failed, attempt ${s}: ${y.sanitizeLogMessage(t?.message ?? String(t))}`
+      ), 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(
+        await this.repository.updateStatus(e.id, n.FAILED, t), c.error("OutboxProcessor: message permanently failed", t, {
+          messageId: e.id,
+          attempts: s
+        }), this.safelyInvokeHook(
           "onPermanentFailure",
           () => this.options.hooks?.onPermanentFailure?.(e, t)
         );
       else if (this.options.retryBackoff) {
-        const { initial: r, multiplier: a, maxDelay: o } = this.options.retryBackoff, g = Math.min(r * Math.pow(a, s - 1), o), c = new Date(Date.now() + g);
-        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 ${g}ms (attempt ${s})`
-        );
+        const { initial: a, multiplier: r, maxDelay: o } = this.options.retryBackoff, h = Math.min(a * Math.pow(r, s - 1), o), u = new Date(Date.now() + h);
+        await this.repository.updateStatus(e.id, n.PENDING), await this.repository.scheduleRetry(e.id, u);
       } else
-        await this.repository.updateStatus(e.id, n.PENDING), this.logger.info(`Message ${e.id} scheduled for retry (attempt ${s + 1})`);
+        await this.repository.updateStatus(e.id, n.PENDING);
     } catch (s) {
-      const r = s instanceof Error ? s.message : String(s);
-      this.logger.error(`Error updating message status: ${r}`);
+      c.error(
+        "OutboxProcessor: error updating message status",
+        s instanceof Error ? s : void 0,
+        { messageId: e.id }
+      );
     }
   }
   /**
@@ -366,8 +434,8 @@ class R {
     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);
+        const r = e + 1, o = r > this.options.adaptiveRepollMaxConsecutive ? this.options.adaptiveRepollPauseMs : 0;
+        this.scheduleProcessing(r, o);
       } else
         this.scheduleProcessing(0, this.options.processingInterval);
     }, t));
@@ -387,19 +455,17 @@ class R {
    * 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));
+    const e = new Date(Date.now() - this.options.crashRecoveryThresholdMs), [t, s] = await g(() => this.repository.resetStaleProcessing(e));
     if (t) {
-      const r = t instanceof Error ? t.message : String(t);
-      this.logger.error(`Crash recovery failed: ${r}`);
+      c.error(
+        "OutboxProcessor: crash recovery failed",
+        t instanceof Error ? t : void 0
+      );
       return;
     }
-    s && s > 0 && this.logger.warn(`Crash recovery reset ${s} stale PROCESSING message(s) to PENDING`);
-  }
-  /**
-   * Logs messages if logging is enabled
-   */
-  log(e) {
-    this.options.enableLogging && this.logger.info(e);
+    s && s > 0 && c.warn(
+      `OutboxProcessor: crash recovery reset ${s} stale PROCESSING message(s) to PENDING`
+    );
   }
   /**
    * Gets processor statistics
@@ -416,7 +482,7 @@ class R {
     };
   }
 }
-class w {
+class I {
   constructor(e) {
     this.eventBus = e;
   }
@@ -432,9 +498,9 @@ class w {
     await this.eventBus.publish(s);
   }
 }
-class P {
+class S {
   constructor(e, t = {}) {
-    this.logger = u.create("OutboxService"), this.repository = e, this.options = {
+    this.repository = e, this.options = {
       defaultPriority: t.defaultPriority ?? l.NORMAL,
       defaultMetadata: t.defaultMetadata ?? {},
       autoCleanup: t.autoCleanup ?? !1,
@@ -446,38 +512,36 @@ class P {
    * Saves a message to the outbox
    */
   async saveMessage(e, t, s) {
-    const r = h.createMessage(e, t, {
+    const a = d.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;
+    });
+    return await this.repository.saveMessage(a);
   }
   /**
    * Saves multiple messages to the outbox in a batch
    */
   async saveMessages(e) {
     const t = e.map(
-      ({ messageType: r, payload: a, options: o }) => h.createMessage(r, a, {
+      ({ messageType: a, payload: r, options: o }) => d.createMessage(a, r, {
         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;
+    );
+    return await this.repository.saveBatch(t);
   }
   /**
    * Schedules a message for delayed processing
    */
-  async scheduleMessage(e, t, s, r) {
-    const a = h.createDelayedMessage(e, t, s, {
+  async scheduleMessage(e, t, s, a) {
+    const r = d.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;
+      metadata: { ...this.options.defaultMetadata, ...a?.metadata },
+      ...a
+    });
+    return await this.repository.scheduleMessage(r, r.processAfter);
   }
   /**
    * Saves a high priority message to the outbox
@@ -501,7 +565,7 @@ class P {
    * Converts a domain event to an outbox message and saves it
    */
   async saveDomainEvent(e, t) {
-    const s = h.createFromIntegrationEvent(
+    const s = d.createFromIntegrationEvent(
       {
         eventName: e.eventName,
         payload: e,
@@ -516,8 +580,8 @@ class P {
         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;
+    );
+    return await this.repository.saveMessage(s);
   }
   /**
    * Gets a message by ID
@@ -535,25 +599,23 @@ class P {
    * Retries a failed message by resetting it to pending status
    */
   async retryMessage(e) {
-    await this.repository.updateStatus(e, n.PENDING), this.logger.info(`Reset message ${e} to pending for retry`);
+    await this.repository.updateStatus(e, n.PENDING);
   }
   /**
    * Retries multiple failed messages
    */
   async retryMessages(e) {
-    await this.repository.updateStatusBatch(e, n.PENDING), this.logger.info(`Reset ${e.length} messages to pending for retry`);
+    await this.repository.updateStatusBatch(e, n.PENDING);
   }
   /**
    * Cleans up old processed messages
    */
   async cleanup(e) {
     const t = e ?? this.options.cleanupAfterDays, s = /* @__PURE__ */ new Date();
-    s.setDate(s.getDate() - t);
-    const r = await this.repository.deleteByStatusAndAge(
+    return s.setDate(s.getDate() - t), await this.repository.deleteByStatusAndAge(
       s,
       n.PROCESSED
     );
-    return this.logger.info(`Cleaned up ${r} processed messages older than ${t} days`), r;
   }
   /**
    * Gets outbox statistics
@@ -575,20 +637,14 @@ class P {
       // Would need separate query
     };
   }
-  /**
-   * Logs messages if logging is enabled
-   */
-  log(e) {
-    this.options.enableLogging && this.logger.info(e);
-  }
 }
 export {
-  w as EventBusOutboxHandler,
-  M as IOutboxRepository,
+  I as EventBusOutboxHandler,
+  w as IOutboxRepository,
   l as MessagePriority,
   n as MessageStatus,
-  h as OutboxMessageFactory,
-  R as OutboxProcessor,
-  P as OutboxService,
-  v as comparePriority
+  d as OutboxMessageFactory,
+  P as OutboxProcessor,
+  S as OutboxService,
+  R as comparePriority
 };

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

@@ -1,4 +1,4 @@
-import { IEventBus } from '../../../contracts/src/index.ts';
+import { IEventBus } from '@vytches/ddd-contracts';
 import { IOutboxMessage, IOutboxMessageHandler, OutboxMiddleware, MessagePriority } from './outbox-interfaces';
 import { IOutboxRepository } from './outbox-repository.interface';
 import { OutboxProcessorHooks } from './outbox-hooks';
@@ -80,6 +80,30 @@ export interface OutboxProcessorOptions {
      * logged and never breaks the processing loop. Omit to disable.
      */
     hooks?: OutboxProcessorHooks;
+    /**
+     * Opt-in: when `true`, `processBatch` calls `IOutboxRepository.claimBatch()`
+     * instead of `getUnprocessedMessages()`, and `processMessage` skips its own
+     * (now redundant) `updateStatus(id, PROCESSING)` call for messages obtained
+     * this way — the repository's `claimBatch` is responsible for the
+     * PROCESSING mark.
+     *
+     * **Correctness depends on the repository.** `claimBatch` is an optional
+     * method on `IOutboxRepository` with a non-atomic default implementation
+     * (read then mark, two steps). Setting `useClaimBatch: true` against a
+     * repository that has NOT overridden `claimBatch` with a real atomic
+     * claim (e.g. `SELECT ... FOR UPDATE SKIP LOCKED`) provides **no**
+     * additional safety over the default `getUnprocessedMessages` path — it
+     * only prevents duplicate dispatch when the repository's `claimBatch` is
+     * genuinely atomic.
+     *
+     * If the repository does not implement `claimBatch` at all (the method is
+     * `undefined`, e.g. a hand-rolled repository predating this option), the
+     * processor logs a warning once and falls back to
+     * `getUnprocessedMessages` for that batch.
+     *
+     * Defaults to `false` — no behavior change for existing consumers (AC#5).
+     */
+    useClaimBatch?: boolean;
 }
 export declare class OutboxProcessor {
     private readonly repository;
@@ -90,7 +114,8 @@ export declare class OutboxProcessor {
     private isRunning;
     private processingTimer?;
     private crashRecoveryTimer?;
-    private readonly logger;
+    /** Guards the one-time fallback warning when `useClaimBatch` is set but the repository has no `claimBatch`. */
+    private warnedMissingClaimBatch;
     constructor(repository: IOutboxRepository, options?: OutboxProcessorOptions);
     /**
      * Invokes an observability hook in isolation. A throwing hook is logged and
@@ -114,8 +139,7 @@ export declare class OutboxProcessor {
      * only types that pass through that filter. To handle all types, leave
      * `messageTypes` unset.
      *
-     * Calling this method a second time silently replaces the previous default
-     * handler (idempotent).
+     * Second/subsequent call emits a warning and replaces the previous handler.
      */
     registerDefaultHandler(handler: IOutboxMessageHandler): void;
     /**
@@ -165,6 +189,9 @@ export declare class OutboxProcessor {
     }>;
     /**
      * Processes a single message through the middleware pipeline.
+     * @param alreadyClaimed When `true`, the message was already marked
+     *   `PROCESSING` by `IOutboxRepository.claimBatch()` — the redundant
+     *   `updateStatus(id, PROCESSING)` call is skipped.
      * @returns `true` if the message was processed successfully, `false` if it failed.
      */
     private processMessage;
@@ -200,10 +227,6 @@ export declare class OutboxProcessor {
      * logged, never thrown — crash recovery must not crash the processor.
      */
     private runCrashRecovery;
-    /**
-     * Logs messages if logging is enabled
-     */
-    private log;
     /**
      * Gets processor statistics
      */

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

@@ -1,4 +1,4 @@
-import { IOutboxMessage, MessagePriority, MessageStatus } from './outbox-interfaces';
+import { MessageStatus, IOutboxMessage, MessagePriority } from './outbox-interfaces';
 export declare abstract class IOutboxRepository {
     /**
      * Saves a message to the outbox
@@ -15,6 +15,23 @@ export declare abstract class IOutboxRepository {
     /**
      * Returns unprocessed messages up to the given limit.
      *
+     * **Not a claim.** This is a pure read — it does not mark returned messages
+     * as `PROCESSING` or otherwise reserve them. `OutboxProcessor` calls
+     * `updateStatus(id, PROCESSING)` for each message *after* this read
+     * returns, which means there is a window between "read" and "claimed"
+     * during which two concurrent processors (or two calls racing on the same
+     * processor) can both read the same PENDING message and both dispatch it.
+     * Multi-worker deployments that need "exactly one processor claims each
+     * message" should implement {@link claimBatch} with an atomic
+     * read+mark (e.g. `SELECT ... FOR UPDATE SKIP LOCKED` or a single
+     * `UPDATE ... WHERE status='PENDING' RETURNING *` statement / compare-
+     * and-swap on `status`) rather than relying on this method plus a
+     * follow-up `updateStatus`.
+     *
+     * Regardless of claim strategy, handlers should be idempotent to side
+     * effects — transient failures or duplicate-claim races may cause a
+     * handler to run more than once.
+     *
      * @param limit - Maximum number of messages to return.
      * @param priorityOrder - Ordered array of MessagePriority values defining
      *   processing order (first element = highest priority, processed first).
@@ -28,6 +45,41 @@ export declare abstract class IOutboxRepository {
      *   returned. When absent, all message types are returned.
      */
     abstract getUnprocessedMessages(limit?: number, priorityOrder?: MessagePriority[], messageTypes?: string[]): Promise<IOutboxMessage[]>;
+    /**
+     * Atomically claims a batch of unprocessed messages: reads PENDING
+     * messages *and* marks them `PROCESSING` in the same operation, so two
+     * concurrent callers (two processor instances, or two racing calls on one
+     * instance) never both receive the same message.
+     *
+     * **Optional, and non-atomic by default.** This method is declared with
+     * `?` — it is NOT part of the required abstract contract, so existing
+     * `IOutboxRepository` subclasses keep compiling unmodified (AC#5). The
+     * default implementation provided here is a convenience shim only: it
+     * calls {@link getUnprocessedMessages} and then `updateStatusBatch(...,
+     * PROCESSING)` as two separate steps. **That is NOT atomic** — it has the
+     * exact same read-then-mark race window as calling
+     * `getUnprocessedMessages` + `updateStatus` manually, and is safe only for
+     * a single-worker deployment. Override `claimBatch` in a concrete
+     * repository (e.g. backed by `SELECT ... FOR UPDATE SKIP LOCKED`, or a
+     * single atomic `UPDATE ... WHERE status='PENDING' LIMIT n RETURNING *`)
+     * to get real multi-worker/multi-processor safety.
+     *
+     * `OutboxProcessor` only calls this method when
+     * `OutboxProcessorOptions.useClaimBatch` is explicitly set to `true`
+     * (opt-in, default `false`) — see AC#1/AC#2. When enabled, the processor
+     * skips its own redundant `updateStatus(id, PROCESSING)` call for messages
+     * returned by `claimBatch`, since claiming already performed that mark.
+     *
+     * Handlers should be idempotent to side effects regardless — transient
+     * failures or duplicate-claim races (e.g. with the non-atomic default
+     * implementation) may still cause a handler to run more than once.
+     *
+     * @param limit - Maximum number of messages to claim.
+     * @param priorityOrder - See {@link getUnprocessedMessages}.
+     * @param messageTypes - See {@link getUnprocessedMessages}.
+     * @returns Messages that were claimed (already marked `PROCESSING`).
+     */
+    claimBatch?(limit?: number, priorityOrder?: MessagePriority[], messageTypes?: string[]): Promise<IOutboxMessage[]>;
     /**
      * Gets specific message by ID
      * @param id Message ID

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

@@ -1,4 +1,4 @@
-import { IDomainEvent } from '../../../contracts/src/index.ts';
+import { IDomainEvent } from '@vytches/ddd-contracts';
 import { IOutboxMessage, OutboxMessageOptions, MessagePriority } from './outbox-interfaces';
 import { IOutboxRepository } from './outbox-repository.interface';
 export interface OutboxServiceOptions {
@@ -16,7 +16,6 @@ export interface OutboxServiceOptions {
 export declare class OutboxService {
     private readonly repository;
     private readonly options;
-    private readonly logger;
     constructor(repository: IOutboxRepository, options?: OutboxServiceOptions);
     /**
      * Saves a message to the outbox
@@ -75,8 +74,4 @@ export declare class OutboxService {
         totalProcessed: number;
         totalFailed: number;
     }>;
-    /**
-     * Logs messages if logging is enabled
-     */
-    private log;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vytches/ddd-messaging",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Outbox pattern and reliable message delivery",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -17,7 +17,8 @@
   "files": [
     "LLMGUIDE.md",
     "README.md",
-    "dist"
+    "dist",
+    "LICENSE"
   ],
   "keywords": [
     "ddd",
@@ -36,7 +37,7 @@
     "typescript": "^5.0.0",
     "vite": "^7.3.2",
     "vite-plugin-dts": "^4.0.0",
-    "vitest": "^4.0.0"
+    "vitest": "^4.1.0"
   },
   "nx": {
     "tags": [
@@ -50,7 +51,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@vytches/ddd-events": "0.30.0"
+    "@vytches/ddd-events": "0.31.0",
+    "@vytches/ddd-contracts": "0.31.0",
+    "@vytches/ddd-utils": "0.31.0"
   },
   "scripts": {
     "build": "vite build",