@web-ts-toolkit/message-service 0.40.1 → 0.41.0

package/index.mjs

@@ -28,13 +28,105 @@ var BaseMessageFields = {
   payload: { type: mongoose.Schema.Types.Mixed, default: {} },
   display: { type: mongoose.Schema.Types.Mixed, default: {} },
   clientRequestId: { type: String, default: null },
-  clientRequestItemIndex: { type: Number, default: null }
+  clientRequestOwnerId: { type: String, default: null },
+  clientRequestItemIndex: { type: Number, default: null },
+  actionState: { type: String, enum: ["active", "processing", "retryable"], default: "active" },
+  actionCd: { type: String, default: null },
+  actionAttemptId: { type: String, default: null },
+  actionClaimedBy: { type: String, default: null },
+  actionClaimedAt: { type: Date, default: null },
+  actionLeaseExpiresAt: { type: Date, default: null },
+  actionFailureMessage: { type: String, default: null }
 };
 
 // src/schemas/message.ts
 import mongoose2 from "mongoose";
 
+// src/runtime-contract.ts
+var ERROR_BRAND_PREFIX = "@web-ts-toolkit/message-service/error/";
+function markRuntimeError(error, name) {
+  Object.defineProperty(error, /* @__PURE__ */ Symbol.for(`${ERROR_BRAND_PREFIX}${name}`), {
+    configurable: false,
+    enumerable: false,
+    value: true
+  });
+}
+function isRuntimeError(value, name) {
+  if (!value || typeof value !== "object") return false;
+  return value.name === name && value[/* @__PURE__ */ Symbol.for(`${ERROR_BRAND_PREFIX}${name}`)] === true;
+}
+
 // src/template-registry.ts
+var TemplateRegistryValidationError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "TemplateRegistryValidationError");
+  }
+  constructor(message) {
+    super(message);
+    this.name = "TemplateRegistryValidationError";
+    markRuntimeError(this, this.name);
+  }
+};
+function requireNonEmptyString(value, field, templateCd) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TemplateRegistryValidationError(
+      `${templateCd ? `template "${templateCd}" ` : ""}${field} must be a non-empty string`
+    );
+  }
+  return value;
+}
+function validateTemplate(template) {
+  const templateCd = requireNonEmptyString(template.templateCd, "templateCd");
+  if (!Array.isArray(template.actions)) {
+    throw new TemplateRegistryValidationError(`template "${templateCd}" actions must be an array`);
+  }
+  const seenActionCodes = /* @__PURE__ */ new Set();
+  const defaultByUsertype = /* @__PURE__ */ new Map();
+  for (const action of template.actions) {
+    const actionCd = requireNonEmptyString(action.actionCd, "actionCd", templateCd);
+    if (seenActionCodes.has(actionCd)) {
+      throw new TemplateRegistryValidationError(`template "${templateCd}" has duplicate actionCd "${actionCd}"`);
+    }
+    seenActionCodes.add(actionCd);
+    requireNonEmptyString(action.name, `action "${actionCd}" name`, templateCd);
+    requireNonEmptyString(action.variant, `action "${actionCd}" variant`, templateCd);
+    if (!action.sender && !action.receiver) {
+      throw new TemplateRegistryValidationError(
+        `template "${templateCd}" action "${actionCd}" must be available to sender or receiver`
+      );
+    }
+    if (action.isDefault) {
+      for (const usertype of ["sender", "receiver"]) {
+        if (!action[usertype]) continue;
+        const existingDefault = defaultByUsertype.get(usertype);
+        if (existingDefault) {
+          throw new TemplateRegistryValidationError(
+            `template "${templateCd}" has multiple default ${usertype} actions: "${existingDefault}" and "${actionCd}"`
+          );
+        }
+        defaultByUsertype.set(usertype, actionCd);
+      }
+    }
+  }
+}
+function snapshotTemplate(template) {
+  const snapshot = {
+    ...template,
+    senderContent: Object.freeze({ ...template.senderContent }),
+    receiverContent: Object.freeze({ ...template.receiverContent }),
+    uiTemplate: typeof template.uiTemplate === "string" ? template.uiTemplate : Object.freeze({ ...template.uiTemplate }),
+    actions: Object.freeze(
+      template.actions.map(
+        (action) => Object.freeze({
+          ...action,
+          confirmation: action.confirmation ? Object.freeze({ ...action.confirmation }) : void 0,
+          payload: action.payload ? Object.freeze({ ...action.payload }) : void 0
+        })
+      )
+    )
+  };
+  return Object.freeze(snapshot);
+}
 var TemplateRegistry = class {
   constructor() {
     this.templates = /* @__PURE__ */ new Map();
@@ -43,7 +135,8 @@ var TemplateRegistry = class {
    * Register a template. Overwrites if templateCd already exists.
    */
   register(template) {
-    this.templates.set(template.templateCd, template);
+    validateTemplate(template);
+    this.templates.set(template.templateCd, snapshotTemplate(template));
   }
   /**
    * Register multiple templates at once.
@@ -90,7 +183,9 @@ var TemplateRegistry = class {
     this.templates.clear();
   }
 };
-var defaultRegistry = new TemplateRegistry();
+var DEFAULT_REGISTRY_KEY = /* @__PURE__ */ Symbol.for("@web-ts-toolkit/message-service/defaultRegistry");
+var registryGlobal = globalThis;
+var defaultRegistry = registryGlobal[DEFAULT_REGISTRY_KEY] ??= new TemplateRegistry();
 function includesAction(templateCd, actionCd, registry) {
   const template = registry.find(templateCd);
   if (!template) return false;
@@ -99,20 +194,53 @@ function includesAction(templateCd, actionCd, registry) {
 
 // src/schemas/methods.ts
 function isSender(user) {
-  return String(this.fromUser) === String(user.id || user._id);
+  const fromUser = normalizeStoredUserId(this.fromUser);
+  const userId = normalizeMessageUserId(user);
+  return fromUser !== null && userId !== null && fromUser === userId;
 }
 function isReceiver(user) {
-  const id = String(user.id || user._id);
-  return String(this.toUser) === id || this.toRoles.some((r) => user.roles?.includes(r));
+  const toUser = normalizeStoredUserId(this.toUser);
+  const userId = normalizeMessageUserId(user);
+  return toUser !== null && userId !== null && toUser === userId || this.toRoles.some((r) => user.roles?.includes(r));
+}
+function normalizeMessageUserId(user) {
+  return normalizeStoredUserId(user?._id ?? null);
+}
+function normalizeStoredUserId(value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  }
+  return String(value);
 }
 
 // src/schemas/message.ts
+function resolveDocumentModel(document, modelName, role) {
+  const model = document.constructor;
+  const connection = model.db;
+  if (!connection) {
+    throw new Error(
+      `message-service: cannot resolve ${role} model "${modelName}" because the hydrated document has no owning connection`
+    );
+  }
+  try {
+    return connection.model(modelName);
+  } catch (error) {
+    const connectionName = connection.name || "<unnamed>";
+    const resolutionError = new Error(
+      `message-service: ${role} model "${modelName}" is not registered on Mongoose connection "${connectionName}"`
+    );
+    resolutionError.cause = error;
+    throw resolutionError;
+  }
+}
 function createArchiveMethod(ctx) {
   return function archive(actionCd, archivedBy, registry) {
     if (!includesAction(this.templateCd, actionCd, registry) || !archivedBy) {
       return Promise.resolve();
     }
-    const MessageArchive = mongoose2.model(ctx.archiveModelName);
+    const MessageArchive = resolveDocumentModel(this, ctx.archiveModelName, "archive");
     const data = this.toObject();
     return MessageArchive.create({
       ...data,
@@ -123,60 +251,118 @@ function createArchiveMethod(ctx) {
     });
   };
 }
-function createPreSaveHook(ctx) {
+var EMAIL_WAS_NEW_LOCAL = "messageServiceEmailWasNew";
+function normalizeEmailTitle(value) {
+  return value.trim().toLowerCase();
+}
+function createEmailStateCaptureHook() {
+  return function captureEmailState() {
+    this.$locals[EMAIL_WAS_NEW_LOCAL] = this.isNew;
+  };
+}
+function createPostSaveEmailHook(ctx) {
   return async function sendNotificationEmail() {
+    if (!this.$locals[EMAIL_WAS_NEW_LOCAL]) {
+      return;
+    }
+    if (this.$session()) {
+      return;
+    }
     if (!this.toUser || !this.receiverContent?.title) {
       return;
     }
     const title = this.receiverContent.title.trim();
-    if (ctx.emailNotificationExclusions.includes(title.toLowerCase())) {
+    if (!title || ctx.emailNotificationExclusions.includes(normalizeEmailTitle(title))) {
+      return;
+    }
+    let user;
+    try {
+      const User = resolveDocumentModel(this, ctx.userModelName, "user");
+      user = await User.findById(this.toUser).select("email").lean();
+    } catch (error) {
+      await reportEmailFailure(ctx, "recipientLookup", error, this, title);
+      return;
+    }
+    if (!user?.email) {
       return;
     }
+    const long = this.receiverContent.long || "";
+    const short = this.receiverContent.short || "";
+    const body = long.length > short.length ? long : short;
     try {
-      const User = mongoose2.model(ctx.userModelName);
-      const user = await User.findById(this.toUser).select("email").lean();
-      if (!user?.email) {
-        return;
-      }
-      const long = this.receiverContent.long || "";
-      const short = this.receiverContent.short || "";
-      const body = long.length > short.length ? long : short;
       await ctx.emailNotifier(user.email, title, body);
-    } catch {
+    } catch (error) {
+      await reportEmailFailure(ctx, "notifier", error, this, title);
     }
   };
 }
-function assertModelRegistered(name, role) {
-  if (!mongoose2.modelNames().includes(name)) {
+async function reportEmailFailure(ctx, stage, error, message, title) {
+  try {
+    await ctx.onEmailDeliveryFailure?.({
+      stage,
+      error,
+      messageId: message._id,
+      recipientId: message.toUser,
+      title
+    });
+  } catch {
+  }
+}
+function assertModelRegistered(connection, name, role) {
+  if (!connection.modelNames().includes(name)) {
+    const connectionName = "name" in connection && connection.name ? connection.name : "global mongoose";
     throw new Error(
-      `message-service: cannot configure schema \u2014 ${role} model "${name}" is not registered with Mongoose. Call mongoose.model("${name}", ...) before buildMessageSchema().`
+      `message-service: cannot configure schema \u2014 ${role} model "${name}" is not registered on Mongoose connection "${connectionName}". Register the model on that connection before buildMessageSchema().`
     );
   }
 }
 function resolveConfig(config) {
   return {
     emailNotifier: config?.emailNotifier ?? null,
-    emailNotificationExclusions: (config?.emailNotificationExclusions ?? []).map((e) => e.toLowerCase()),
+    onEmailDeliveryFailure: config?.onEmailDeliveryFailure,
+    emailNotificationExclusions: (config?.emailNotificationExclusions ?? []).map(normalizeEmailTitle),
     userModelName: config?.userModelName ?? "User",
-    archiveModelName: config?.archiveModelName ?? MESSAGE_ARCHIVE_MODEL_NAME
+    archiveModelName: config?.archiveModelName ?? MESSAGE_ARCHIVE_MODEL_NAME,
+    connection: config?.connection ?? mongoose2
   };
 }
 function buildMessageSchema(config) {
   const resolved = resolveConfig(config);
   if (resolved.emailNotifier) {
-    assertModelRegistered(resolved.userModelName, "user");
+    assertModelRegistered(resolved.connection, resolved.userModelName, "user");
   }
   const schema = new mongoose2.Schema(BaseMessageFields, {
     timestamps: true
   });
-  schema.index({ createdAt: 1 });
-  schema.index({ clientRequestId: 1 }, { sparse: true });
+  schema.index({ fromUser: 1, createdAt: -1, _id: -1 });
+  schema.index({ toUser: 1, createdAt: -1, _id: -1 });
+  schema.index({ toRoles: 1, createdAt: -1, _id: -1 });
+  schema.index({ actionState: 1, actionLeaseExpiresAt: 1 });
   schema.index(
-    { clientRequestId: 1, clientRequestItemIndex: 1 },
+    { actionAttemptId: 1 },
     {
       unique: true,
+      partialFilterExpression: { actionAttemptId: { $type: "string" } }
+    }
+  );
+  schema.index(
+    { clientRequestOwnerId: 1, templateCd: 1, clientRequestId: 1, createdAt: 1, _id: 1 },
+    {
       partialFilterExpression: {
         clientRequestId: { $type: "string" },
+        clientRequestOwnerId: { $type: "string" },
+        templateCd: { $type: "string" }
+      }
+    }
+  );
+  schema.index(
+    { clientRequestOwnerId: 1, templateCd: 1, clientRequestId: 1, clientRequestItemIndex: 1 },
+    {
+      unique: true,
+      partialFilterExpression: {
+        clientRequestId: { $type: "string" },
+        clientRequestOwnerId: { $type: "string" },
+        templateCd: { $type: "string" },
         clientRequestItemIndex: { $type: "number" }
       }
     }
@@ -185,10 +371,12 @@ function buildMessageSchema(config) {
   schema.methods.isReceiver = isReceiver;
   schema.methods.archive = createArchiveMethod({ archiveModelName: resolved.archiveModelName });
   if (resolved.emailNotifier) {
-    schema.pre(
+    schema.pre("save", createEmailStateCaptureHook());
+    schema.post(
       "save",
-      createPreSaveHook({
+      createPostSaveEmailHook({
         emailNotifier: resolved.emailNotifier,
+        onEmailDeliveryFailure: resolved.onEmailDeliveryFailure,
         emailNotificationExclusions: resolved.emailNotificationExclusions,
         userModelName: resolved.userModelName
       })
@@ -206,7 +394,11 @@ function buildMessageArchiveSchema() {
       ...BaseMessageFields,
       actionCd: { type: String, default: "" },
       archivedBy: { type: mongoose3.Schema.Types.ObjectId, default: null, index: true },
-      archivedAt: { type: Date, default: Date.now }
+      archivedAt: { type: Date, default: Date.now },
+      actionAttemptId: { type: String, default: null, index: true },
+      actionNotificationState: { type: String, enum: ["none", "pending", "sent", "failed"], default: "none" },
+      actionNotificationError: { type: String, default: null },
+      actionNotificationAttemptedAt: { type: Date, default: null }
     },
     {
       timestamps: true
@@ -225,15 +417,23 @@ function buildMessageRequestSchema() {
   const schema = new mongoose4.Schema(
     {
       clientRequestId: { type: String, required: true },
-      state: { type: String, enum: ["pending", "completed"], default: "pending" },
-      itemCount: { type: Number, default: null }
+      clientRequestOwnerId: { type: String, required: true },
+      templateCd: { type: String, required: true },
+      state: { type: String, enum: ["pending", "completed", "failed"], default: "pending" },
+      itemCount: { type: Number, default: null },
+      leaseOwnerId: { type: String, default: null },
+      leaseExpiresAt: { type: Date, default: null },
+      completedAt: { type: Date, default: null },
+      failedAt: { type: Date, default: null },
+      failureMessage: { type: String, default: null }
     },
     {
       timestamps: true
     }
   );
-  schema.index({ clientRequestId: 1 }, { unique: true });
+  schema.index({ clientRequestOwnerId: 1, templateCd: 1, clientRequestId: 1 }, { unique: true });
   schema.index({ updatedAt: 1 });
+  schema.index({ state: 1, leaseExpiresAt: 1 });
   return schema;
 }
 var MessageRequestSchema = buildMessageRequestSchema();
@@ -324,52 +524,254 @@ var NoopPaymentProvider = class {
 
 // src/message-service.ts
 import { isString } from "@web-ts-toolkit/utils";
+import { randomUUID } from "crypto";
+import mongoose5 from "mongoose";
 var DEFAULT_LIST_LIMIT = 50;
 var MAX_LIST_LIMIT = 100;
 var DUPLICATE_KEY_ERROR_CODE = 11e3;
-var CLIENT_REQUEST_BATCH_RETRY_COUNT = 20;
-var CLIENT_REQUEST_BATCH_RETRY_DELAY_MS = 10;
+var CLIENT_REQUEST_LEASE_MS = 3e4;
+var CLIENT_REQUEST_WAIT_MS = 5e3;
+var CLIENT_REQUEST_POLL_MS = 200;
+var ACTION_LEASE_MS = 3e4;
+var MAX_CLIENT_REQUEST_ID_LENGTH = 128;
+var TRANSACTION_REQUIRED_MESSAGE = "message-service requires MongoDB replica set or sharded-cluster transactions for idempotent batch creation";
+var DEFAULT_MODEL_NAMES = {
+  active: MESSAGE_MODEL_NAME,
+  archive: MESSAGE_ARCHIVE_MODEL_NAME,
+  request: MESSAGE_REQUEST_MODEL_NAME,
+  user: "User"
+};
 var GENERIC_NOTIFICATION_TEMPLATE_CD = "__generic-notification__";
 var MessageNotFoundError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "MessageNotFoundError");
+  }
   constructor(messageId) {
     super(`message "${messageId}" not found`);
     this.name = "MessageNotFoundError";
+    markRuntimeError(this, this.name);
   }
 };
 var MessageArchivedError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "MessageArchivedError");
+  }
   constructor(messageId) {
     super(`message "${messageId}" is archived`);
     this.name = "MessageArchivedError";
+    markRuntimeError(this, this.name);
   }
 };
 var TemplateNotFoundError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "TemplateNotFoundError");
+  }
   constructor(templateCd) {
     super(`template "${templateCd}" not found`);
     this.name = "TemplateNotFoundError";
+    markRuntimeError(this, this.name);
   }
 };
 var ActionNotFoundError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "ActionNotFoundError");
+  }
   constructor(templateCd, actionCd) {
     super(`action "${actionCd}" not found in template "${templateCd}"`);
     this.name = "ActionNotFoundError";
+    markRuntimeError(this, this.name);
   }
 };
 var ActionNotAllowedError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "ActionNotAllowedError");
+  }
   constructor() {
     super("not allowed");
     this.name = "ActionNotAllowedError";
+    markRuntimeError(this, this.name);
+  }
+};
+var InvalidMessageUserError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "InvalidMessageUserError");
+  }
+  constructor(message = "user._id must be a non-empty string or ObjectId") {
+    super(message);
+    this.name = "InvalidMessageUserError";
+    markRuntimeError(this, this.name);
+  }
+};
+var ActionTemplateMismatchError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "ActionTemplateMismatchError");
+  }
+  constructor(expectedTemplateCd, receivedTemplateCd) {
+    super(`message template "${expectedTemplateCd}" does not match requested template "${receivedTemplateCd}"`);
+    this.name = "ActionTemplateMismatchError";
+    markRuntimeError(this, this.name);
+  }
+};
+var ActionConflictError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "ActionConflictError");
+  }
+  constructor(messageId) {
+    super(`message "${messageId}" already has an action in progress`);
+    this.name = "ActionConflictError";
+    markRuntimeError(this, this.name);
+  }
+};
+var ActionRetryableError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "ActionRetryableError");
+  }
+  constructor(messageId, actionAttemptId, cause) {
+    super(`message "${messageId}" action attempt "${actionAttemptId}" failed before commit and may be retried`);
+    this.name = "ActionRetryableError";
+    markRuntimeError(this, this.name);
+    this.actionAttemptId = actionAttemptId;
+    if (cause) {
+      this.cause = cause;
+    }
+  }
+};
+var ActionNotificationPendingError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "ActionNotificationPendingError");
+  }
+  constructor(messageId, actionAttemptId, result, cause) {
+    super(`message "${messageId}" action committed but sender notification is pending`);
+    this.name = "ActionNotificationPendingError";
+    markRuntimeError(this, this.name);
+    this.actionAttemptId = actionAttemptId;
+    this.result = result;
+    if (cause) {
+      this.cause = cause;
+    }
+  }
+};
+var InvalidClientRequestIdError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "InvalidClientRequestIdError");
+  }
+  constructor(message) {
+    super(message);
+    this.name = "InvalidClientRequestIdError";
+    markRuntimeError(this, this.name);
+  }
+};
+var InvalidPaginationValueError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "InvalidPaginationValueError");
+  }
+  constructor(message) {
+    super(message);
+    this.name = "InvalidPaginationValueError";
+    markRuntimeError(this, this.name);
+  }
+};
+var ClientRequestPendingError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "ClientRequestPendingError");
+  }
+  constructor(clientRequestId) {
+    super(
+      `clientRequestId "${clientRequestId}" is still pending; retry after the current reservation completes or its lease expires`
+    );
+    this.name = "ClientRequestPendingError";
+    markRuntimeError(this, this.name);
+  }
+};
+var ClientRequestFailedError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "ClientRequestFailedError");
+  }
+  constructor(clientRequestId, reason) {
+    super(`clientRequestId "${clientRequestId}" previously failed${reason ? `: ${reason}` : ""}`);
+    this.name = "ClientRequestFailedError";
+    markRuntimeError(this, this.name);
+  }
+};
+var ClientRequestInconsistentStateError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "ClientRequestInconsistentStateError");
+  }
+  constructor(clientRequestId, message) {
+    super(`clientRequestId "${clientRequestId}" has inconsistent persisted state: ${message}`);
+    this.name = "ClientRequestInconsistentStateError";
+    markRuntimeError(this, this.name);
+  }
+};
+var MessageTransactionRequiredError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "MessageTransactionRequiredError");
+  }
+  constructor(cause) {
+    super(TRANSACTION_REQUIRED_MESSAGE);
+    this.name = "MessageTransactionRequiredError";
+    markRuntimeError(this, this.name);
+    if (cause) {
+      this.cause = cause;
+    }
+  }
+};
+var MessageModelResolutionError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "MessageModelResolutionError");
+  }
+  constructor(role, modelName, connectionName, cause) {
+    super(`message-service could not resolve ${role} model "${modelName}" on ${connectionName}`);
+    this.name = "MessageModelResolutionError";
+    markRuntimeError(this, this.name);
+    this.role = role;
+    this.modelName = modelName;
+    this.connectionName = connectionName;
+    if (cause) {
+      this.cause = cause;
+    }
+  }
+};
+var PaymentSessionCompensationError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "PaymentSessionCompensationError");
+  }
+  constructor(sessionId, operation, compensationError, originalError, hookError) {
+    super(`payment session compensation failed for session "${sessionId}" during ${operation}`);
+    this.name = "PaymentSessionCompensationError";
+    markRuntimeError(this, this.name);
+    this.sessionId = sessionId;
+    this.operation = operation;
+    this.compensationError = compensationError;
+    this.originalError = originalError;
+    this.hookError = hookError;
+    this.cause = compensationError;
   }
 };
 var MessageService = class {
   constructor(options) {
     this.getModel = options.getModel;
+    this.connection = options.connection;
+    this.modelNames = { ...DEFAULT_MODEL_NAMES, ...options.modelNames };
     this.paymentProvider = options.paymentProvider ?? null;
     this.expirePaymentSession = this.paymentProvider?.expireSession.bind(this.paymentProvider);
     this.refundPaymentSession = this.paymentProvider?.refundPayment.bind(this.paymentProvider);
+    this.onPaymentCompensationFailure = options.onPaymentCompensationFailure;
     this.adminRoles = options.adminRoles ?? [];
     this.registry = options.registry ?? defaultRegistry;
-    this.defaultListLimit = options.defaultListLimit ?? DEFAULT_LIST_LIMIT;
-    this.maxListLimit = options.maxListLimit ?? MAX_LIST_LIMIT;
+    this.maxListLimit = this.validatePositiveIntegerOption("maxListLimit", options.maxListLimit ?? MAX_LIST_LIMIT);
+    this.defaultListLimit = this.validatePositiveIntegerOption(
+      "defaultListLimit",
+      options.defaultListLimit ?? DEFAULT_LIST_LIMIT
+    );
+    if (this.defaultListLimit > this.maxListLimit) {
+      throw new InvalidPaginationValueError("defaultListLimit must be less than or equal to maxListLimit");
+    }
+    this.clientRequestLeaseMs = options.clientRequestLeaseMs ?? CLIENT_REQUEST_LEASE_MS;
+    this.clientRequestWaitMs = options.clientRequestWaitMs ?? CLIENT_REQUEST_WAIT_MS;
+    this.clientRequestPollMs = options.clientRequestPollMs ?? CLIENT_REQUEST_POLL_MS;
+    this.clientRequestDelay = options.clientRequestDelay ?? this.delay;
+    this.actionLeaseMs = ACTION_LEASE_MS;
   }
   // -------------------------------------------------------------------------
   // Message lookup
@@ -379,8 +781,8 @@ var MessageService = class {
    * the message does not exist in either collection.
    */
   async findMessage(messageId, options = {}) {
-    const Message = this.getModel(MESSAGE_MODEL_NAME);
-    const MessageArchive = this.getModel(MESSAGE_ARCHIVE_MODEL_NAME);
+    const Message = this.resolveModel("active");
+    const MessageArchive = this.resolveModel("archive");
     const message = await this.findByIdWithOptions(Message, messageId, options);
     if (message) return message;
     return await this.findByIdWithOptions(
@@ -411,7 +813,8 @@ var MessageService = class {
       req,
       clientRequestId
     } = params;
-    if (clientRequestId) {
+    const normalizedClientRequestId = this.normalizeClientRequestId(clientRequestId);
+    if (normalizedClientRequestId) {
       return this.createMessageWithReservation({
         templateCd,
         user,
@@ -421,7 +824,7 @@ var MessageService = class {
         payload,
         payerUser,
         req,
-        clientRequestId
+        clientRequestId: normalizedClientRequestId
       });
     }
     return this.createPreparedMessageBatch({
@@ -436,31 +839,38 @@ var MessageService = class {
     });
   }
   async createMessageWithReservation(params) {
-    while (true) {
-      const existing = await this.findByClientRequestId(params.clientRequestId);
-      if (existing) {
-        return existing;
-      }
-      const acquired = await this.tryCreateClientRequestReservation(params.clientRequestId);
-      if (acquired) {
-        break;
-      }
-      const waited = await this.waitForClientRequestOutcome(params.clientRequestId);
-      if (waited !== null) {
-        return waited;
-      }
-    }
+    const clientRequestScope = this.buildClientRequestScope(params.clientRequestId, params.user, params.templateCd);
+    const replay = await this.findCompletedClientRequestReplay(clientRequestScope);
+    if (replay !== null) return replay;
+    const start = await this.acquireClientRequestStart(clientRequestScope);
+    if (start.kind === "replay") return start.replay;
     try {
-      const results = await this.createPreparedMessageBatch(params);
-      await this.completeClientRequestReservation(params.clientRequestId, results.length);
+      const results = await this.createPreparedMessageBatch({
+        ...params,
+        clientRequestScope,
+        clientRequestLease: start.lease
+      });
       return results;
     } catch (error) {
-      await this.releaseClientRequestReservation(params.clientRequestId);
+      if (!(error instanceof ClientRequestPendingError)) {
+        await this.failClientRequestReservation(clientRequestScope, start.lease, error);
+      }
       throw error;
     }
   }
   async createPreparedMessageBatch(params) {
-    const { templateCd, user, roles, identity, permissions, payload, payerUser, req, clientRequestId } = params;
+    const {
+      templateCd,
+      user,
+      roles,
+      identity,
+      permissions,
+      payload,
+      payerUser,
+      req,
+      clientRequestScope,
+      clientRequestLease
+    } = params;
     const template = this.registry.find(templateCd);
     if (!template) throw new TemplateNotFoundError(templateCd);
     const messageData = await template.prepareMessage({
@@ -469,24 +879,36 @@ var MessageService = class {
       identity,
       permissions,
       payload,
-      getModel: this.getModel,
+      getModel: this.getTemplateModelResolver(),
       req
     });
-    if (!messageData) return [];
+    if (!messageData) {
+      if (clientRequestScope && clientRequestLease) {
+        await this.persistPreparedBatchTransaction(clientRequestScope, clientRequestLease, []);
+      }
+      return [];
+    }
     const ctx = { user, roles, identity, permissions, payload, payerUser, req };
     const items = Array.isArray(messageData) ? messageData : [messageData];
+    if (clientRequestScope && clientRequestLease) {
+      const docs = [];
+      for (let index = 0; index < items.length; index++) {
+        docs.push(await this.buildMessageDocument(template, items[index], ctx, clientRequestScope, index));
+      }
+      return this.persistPreparedBatchTransaction(clientRequestScope, clientRequestLease, docs);
+    }
     const results = [];
     for (let index = 0; index < items.length; index++) {
       const item = items[index];
-      results.push(await this.persistItem(template, item, ctx, clientRequestId, clientRequestId ? index : null));
+      results.push(await this.persistItem(template, item, ctx, clientRequestScope, clientRequestScope ? index : null));
     }
     return results;
   }
   // -------------------------------------------------------------------------
   // Create generic notification (no template, no actions)
   // -------------------------------------------------------------------------
-  async createNotification(params) {
-    const Message = this.getModel(MESSAGE_MODEL_NAME);
+  async createNotification(params, sourceDocument) {
+    const Message = this.resolveModel("active", sourceDocument);
     return Message.create({
       type: "notification",
       templateCd: GENERIC_NOTIFICATION_TEMPLATE_CD,
@@ -507,7 +929,7 @@ var MessageService = class {
    * queries (e.g. with `populate`).
    */
   buildVisibilityFilter(user) {
-    const userId = user.id || String(user._id);
+    const userId = this.requireUserId(user);
     return {
       $or: [{ fromUser: userId }, { toUser: userId }, { toRoles: { $in: user.roles ?? [] } }]
     };
@@ -519,11 +941,11 @@ var MessageService = class {
    */
   async listMessages(params) {
     const { user, limit: rawLimit, skip: rawSkip, populate } = params;
-    const limit = Math.min(Math.max(rawLimit ?? this.defaultListLimit, 1), this.maxListLimit);
-    const skip = Math.max(rawSkip ?? 0, 0);
-    const Message = this.getModel(MESSAGE_MODEL_NAME);
+    const limit = this.normalizeListLimit(rawLimit);
+    const skip = this.normalizeListSkip(rawSkip);
+    const Message = this.resolveModel("active");
     const query = this.applyPopulate(
-      Message.find(this.buildVisibilityFilter(user)).sort({ createdAt: -1 }).skip(skip).limit(limit),
+      Message.find(this.buildVisibilityFilter(user)).sort({ createdAt: -1, _id: -1 }).skip(skip).limit(limit),
       populate
     );
     return query;
@@ -533,7 +955,7 @@ var MessageService = class {
    * Useful for badge indicators ("3 new messages").
    */
   async countMessages(user) {
-    const Message = this.getModel(MESSAGE_MODEL_NAME);
+    const Message = this.resolveModel("active");
     return Message.countDocuments(this.buildVisibilityFilter(user));
   }
   // -------------------------------------------------------------------------
@@ -542,8 +964,10 @@ var MessageService = class {
   async getActions(messageId, usertype, options = {}) {
     const message = options.message ?? await this.findMessage(messageId, { populate: options.populate });
     if (!message) return null;
-    if (!options.isAdmin && options.user) {
-      const isAllowedUsertype = usertype === "sender" ? message.isSender(options.user) : message.isReceiver(options.user);
+    const user = this.requireUserId(options.user);
+    const authorizedUser = { ...options.user, _id: user };
+    if (!options.isAdmin) {
+      const isAllowedUsertype = usertype === "sender" ? message.isSender(authorizedUser) : message.isReceiver(authorizedUser);
       if (!isAllowedUsertype) {
         return null;
       }
@@ -558,7 +982,7 @@ var MessageService = class {
       permissions: options.permissions,
       message
     });
-    if (options.isAdmin) {
+    if (options.isAdmin || this.isArchivedMessage(message)) {
       return { uiTemplate: interpolated.uiTemplate, actions: [] };
     }
     return { uiTemplate: interpolated.uiTemplate, actions: interpolated.actions };
@@ -567,68 +991,387 @@ var MessageService = class {
   // Handle an action on a message
   // -------------------------------------------------------------------------
   async handleAction(templateCd, actionCd, data) {
+    const userId = this.requireUserId(data.user);
+    const authorizedUser = { ...data.user, _id: userId };
     if (this.isArchivedMessage(data.message)) {
+      if (data.message.actionNotificationState === "pending" || data.message.actionNotificationState === "failed") {
+        throw new ActionNotificationPendingError(
+          String(data.message._id),
+          data.message.actionAttemptId ?? "",
+          void 0
+        );
+      }
       throw new MessageArchivedError(String(data.message._id));
     }
-    const template = this.registry.find(templateCd);
-    if (!template) throw new TemplateNotFoundError(templateCd);
+    if (templateCd !== data.message.templateCd) {
+      throw new ActionTemplateMismatchError(data.message.templateCd, templateCd);
+    }
+    const template = this.registry.find(data.message.templateCd);
+    if (!template) throw new TemplateNotFoundError(data.message.templateCd);
     const action = template.actions.find((a) => a.actionCd === actionCd);
-    if (!action) throw new ActionNotFoundError(templateCd, actionCd);
-    if (!isActionAllowed(action, data.user, data.message, { permissions: data.permissions })) {
+    if (!action) throw new ActionNotFoundError(data.message.templateCd, actionCd);
+    if (!isActionAllowed(action, authorizedUser, data.message, { permissions: data.permissions })) {
       throw new ActionNotAllowedError();
     }
-    const ctx = this.buildActionContext(data);
-    const result = await action.runHandler(ctx);
-    await data.message.archive(actionCd, data.user._id, this.registry);
-    await this.runSenderNotification(action, ctx, data.message);
+    const claim = await this.claimAction(data.message, actionCd, authorizedUser);
+    const ctx = this.buildActionContext({
+      ...data,
+      user: authorizedUser,
+      message: claim.message,
+      actionAttemptId: claim.actionAttemptId
+    });
+    let result;
+    try {
+      result = await action.runHandler(ctx);
+    } catch (error) {
+      await this.markActionRetryable(data.message._id, claim.actionAttemptId, error, claim.message);
+      throw new ActionRetryableError(String(data.message._id), claim.actionAttemptId, error);
+    }
+    await this.archiveClaimedMessage(claim.message, action, authorizedUser, claim.actionAttemptId);
+    if (action.senderNotification) {
+      try {
+        await this.runSenderNotification(action, ctx, claim.message);
+        await this.markActionNotificationState(
+          data.message._id,
+          claim.actionAttemptId,
+          "sent",
+          void 0,
+          claim.message
+        );
+      } catch (error) {
+        await this.markActionNotificationState(data.message._id, claim.actionAttemptId, "failed", error, claim.message);
+        throw new ActionNotificationPendingError(String(data.message._id), claim.actionAttemptId, result, error);
+      }
+    }
     return result;
   }
   // -------------------------------------------------------------------------
   // Private helpers
   // -------------------------------------------------------------------------
-  async persistItem(template, m, ctx, clientRequestId, clientRequestItemIndex) {
+  resolveModel(role, sourceDocument, sourceModel) {
+    const modelName = this.modelNames[role];
+    const sourceConnection = this.getModelConnection(sourceModel) ?? this.getDocumentConnection(sourceDocument);
+    try {
+      if (this.getModel) {
+        const model = this.getModel(modelName);
+        if (!model) {
+          throw new Error(`resolver returned no model for "${modelName}"`);
+        }
+        const resolvedConnection = this.getModelConnection(model);
+        if (sourceConnection && resolvedConnection && resolvedConnection !== sourceConnection) {
+          throw new Error(
+            `resolver returned model "${modelName}" from connection "${resolvedConnection.name || "<unnamed>"}" instead of source connection "${sourceConnection.name || "<unnamed>"}"`
+          );
+        }
+        return model;
+      }
+      if (sourceConnection) {
+        return sourceConnection.model(modelName);
+      }
+      if (this.connection) {
+        return this.connection.model(modelName);
+      }
+      return mongoose5.model(modelName);
+    } catch (error) {
+      throw new MessageModelResolutionError(role, modelName, this.describeModelSource(sourceConnection), error);
+    }
+  }
+  getTemplateModelResolver(sourceDocument) {
+    const sourceConnection = this.getDocumentConnection(sourceDocument);
+    return (name) => {
+      try {
+        if (sourceConnection) return sourceConnection.model(name);
+        if (this.getModel) return this.getModel(name);
+        if (this.connection) return this.connection.model(name);
+        return mongoose5.model(name);
+      } catch (error) {
+        throw new MessageModelResolutionError("user", name, this.describeModelSource(sourceConnection), error);
+      }
+    };
+  }
+  getDocumentConnection(sourceDocument) {
+    if (!sourceDocument) return void 0;
+    const model = sourceDocument.constructor;
+    return this.getModelConnection(model);
+  }
+  getModelConnection(model) {
+    const connection = model?.db;
+    return connection && typeof connection.model === "function" ? connection : void 0;
+  }
+  describeModelSource(sourceConnection) {
+    const connection = sourceConnection ?? this.connection;
+    if (connection) {
+      return `Mongoose connection "${connection.name || "<unnamed>"}"`;
+    }
+    if (this.getModel) {
+      return "the configured model resolver";
+    }
+    return "global mongoose";
+  }
+  async persistItem(template, m, ctx, clientRequestScope, clientRequestItemIndex) {
+    const Message = this.resolveModel("active");
+    const doc = await this.buildMessageDocument(template, m, ctx, clientRequestScope, clientRequestItemIndex);
+    try {
+      return await Message.create(doc);
+    } catch (error) {
+      await this.compensatePaymentSessions([doc], error, clientRequestScope);
+      throw error;
+    }
+  }
+  async buildMessageDocument(template, m, ctx, clientRequestScope, clientRequestItemIndex) {
     const toUser = m.toUser ?? null;
     const toRoles = (m.toRoles && m.toRoles.length > 0 ? m.toRoles : this.adminRoles).slice();
     const type = m.type || template.type || "notification";
     const paymentCd = m.paymentCd || template.paymentCd || "";
     let paymentSession = null;
-    if (paymentCd && this.paymentProvider && (toUser || toRoles.length > 0)) {
-      paymentSession = await this.paymentProvider.createSession(
-        (ctx.payerUser || ctx.user)._id,
+    try {
+      if (paymentCd && this.paymentProvider && (toUser || toRoles.length > 0)) {
+        paymentSession = await this.paymentProvider.createSession(
+          (ctx.payerUser || ctx.user)._id,
+          paymentCd,
+          m.priceArgs
+        );
+        if (!paymentSession) throw new Error("payment session creation failed");
+      }
+      const interpolated = interpolateTemplate(template, m.templateData || {}, "receiver");
+      return {
+        type,
+        templateCd: template.templateCd,
+        fromUser: m.fromUser || ctx.user._id,
+        toUser,
+        toRoles,
+        senderContent: interpolated.senderContent,
+        receiverContent: interpolated.receiverContent,
+        documents: ctx.payload.documents || [],
+        paymentSession,
         paymentCd,
-        m.priceArgs
+        payload: m.payload || ctx.payload,
+        display: m.display,
+        clientRequestId: clientRequestScope?.clientRequestId ?? null,
+        clientRequestOwnerId: clientRequestScope?.clientRequestOwnerId ?? null,
+        clientRequestItemIndex
+      };
+    } catch (error) {
+      if (paymentSession) {
+        await this.compensatePaymentSession(paymentSession, error, clientRequestScope);
+      }
+      throw error;
+    }
+  }
+  async persistPreparedBatchTransaction(scope, lease, docs) {
+    const Message = this.resolveModel("active");
+    const MessageRequest = this.resolveModel("request", void 0, Message);
+    const operation = async (session2) => {
+      const created = docs.length > 0 ? await Message.create(docs, session2 ? { session: session2, ordered: true } : void 0) : [];
+      const result = await MessageRequest.updateOne(
+        { ...scope, state: "pending", leaseOwnerId: lease.ownerId },
+        {
+          $set: {
+            state: "completed",
+            itemCount: docs.length,
+            completedAt: /* @__PURE__ */ new Date(),
+            leaseExpiresAt: null
+          }
+        },
+        session2 ? { session: session2 } : void 0
       );
-      if (!paymentSession) throw new Error("payment session creation failed");
+      if ((result.matchedCount ?? result.n ?? 0) !== 1) {
+        throw new ClientRequestPendingError(scope.clientRequestId);
+      }
+      return created;
+    };
+    const startSession = Message.db?.startSession;
+    if (!startSession) {
+      try {
+        return await operation();
+      } catch (error) {
+        await this.compensatePaymentSessions(docs, error, scope);
+        throw error;
+      }
+    }
+    const session = await startSession.call(Message.db);
+    try {
+      let result = [];
+      await session.withTransaction(async () => {
+        result = await operation(session);
+      });
+      return result;
+    } catch (error) {
+      const wrappedError = this.isTransactionSupportError(error) ? new MessageTransactionRequiredError(error) : error;
+      await this.compensatePaymentSessions(docs, wrappedError, scope);
+      if (this.isTransactionSupportError(error)) {
+        throw wrappedError;
+      }
+      throw wrappedError;
+    } finally {
+      await session.endSession();
+    }
+  }
+  async compensatePaymentSessions(docs, originalError, scope) {
+    const sessionIds = docs.map((doc) => doc.paymentSession).filter((sessionId) => typeof sessionId === "string" && sessionId.length > 0);
+    for (const sessionId of sessionIds) {
+      await this.compensatePaymentSession(sessionId, originalError, scope);
+    }
+  }
+  async compensatePaymentSession(sessionId, originalError, scope) {
+    if (!this.expirePaymentSession) return;
+    try {
+      await this.expirePaymentSession(sessionId);
+    } catch (error) {
+      let hookError;
+      try {
+        await this.onPaymentCompensationFailure?.({
+          operation: "expire",
+          sessionId,
+          error,
+          originalError,
+          clientRequestId: scope?.clientRequestId,
+          clientRequestOwnerId: scope?.clientRequestOwnerId,
+          templateCd: scope?.templateCd
+        });
+      } catch (eventError) {
+        hookError = eventError;
+      }
+      throw new PaymentSessionCompensationError(sessionId, "expire", error, originalError, hookError);
     }
-    const interpolated = interpolateTemplate(template, m.templateData || {}, "receiver");
-    const Message = this.getModel(MESSAGE_MODEL_NAME);
-    return Message.create({
-      type,
-      templateCd: template.templateCd,
-      fromUser: m.fromUser || ctx.user._id,
-      toUser,
-      toRoles,
-      senderContent: interpolated.senderContent,
-      receiverContent: interpolated.receiverContent,
-      documents: ctx.payload.documents || [],
-      paymentSession,
-      paymentCd,
-      payload: m.payload || ctx.payload,
-      display: m.display,
-      clientRequestId: clientRequestId ?? null,
-      clientRequestItemIndex
-    });
   }
   buildActionContext(data) {
     return {
       message: data.message,
       user: data.user,
-      getModel: this.getModel,
+      actionAttemptId: data.actionAttemptId,
+      getModel: this.getTemplateModelResolver(data.message),
       expireSession: this.expirePaymentSession,
       refundPayment: this.refundPaymentSession,
       req: data.req
     };
   }
+  async claimAction(message, actionCd, user) {
+    const Message = this.resolveModel("active", message);
+    const messageId = message._id;
+    const now = /* @__PURE__ */ new Date();
+    const claimBase = {
+      actionCd,
+      actionClaimedBy: String(user._id),
+      actionClaimedAt: now,
+      actionLeaseExpiresAt: new Date(now.getTime() + this.actionLeaseMs),
+      actionFailureMessage: null
+    };
+    const firstAttemptId = randomUUID();
+    const firstClaim = await Message.findOneAndUpdate(
+      { _id: messageId, $or: [{ actionState: "active" }, { actionState: null }, { actionState: { $exists: false } }] },
+      { $set: { ...claimBase, actionState: "processing", actionAttemptId: firstAttemptId } },
+      { returnDocument: "after" }
+    );
+    if (firstClaim?.actionAttemptId) {
+      return { message: firstClaim, actionAttemptId: firstClaim.actionAttemptId };
+    }
+    const retryClaim = await Message.findOneAndUpdate(
+      {
+        _id: messageId,
+        actionCd,
+        actionAttemptId: { $type: "string" },
+        $or: [{ actionState: "retryable" }, { actionState: "processing", actionLeaseExpiresAt: { $lte: now } }]
+      },
+      { $set: { ...claimBase, actionState: "processing" } },
+      { returnDocument: "after" }
+    );
+    if (retryClaim?.actionAttemptId) {
+      return { message: retryClaim, actionAttemptId: retryClaim.actionAttemptId };
+    }
+    const archived = await this.resolveModel("archive", message, Message).findById(
+      messageId
+    );
+    if (archived) {
+      if (archived.actionNotificationState === "pending" || archived.actionNotificationState === "failed") {
+        throw new ActionNotificationPendingError(String(messageId), archived.actionAttemptId ?? "", void 0);
+      }
+      throw new MessageArchivedError(String(messageId));
+    }
+    throw new ActionConflictError(String(messageId));
+  }
+  async markActionRetryable(messageId, actionAttemptId, error, sourceDocument) {
+    const Message = this.resolveModel("active", sourceDocument);
+    await Message.updateOne(
+      { _id: messageId, actionState: "processing", actionAttemptId },
+      {
+        $set: {
+          actionState: "retryable",
+          actionFailureMessage: error instanceof Error ? error.message : String(error),
+          actionLeaseExpiresAt: null
+        }
+      }
+    );
+  }
+  async archiveClaimedMessage(message, action, user, actionAttemptId) {
+    const Message = this.resolveModel("active", message);
+    const MessageArchive = this.resolveModel("archive", message, Message);
+    const messageId = message._id;
+    const data = message.toObject();
+    const notificationState = action.senderNotification ? "pending" : "none";
+    delete data.actionState;
+    delete data.actionClaimedBy;
+    delete data.actionClaimedAt;
+    delete data.actionLeaseExpiresAt;
+    delete data.actionFailureMessage;
+    const operation = async (session2) => {
+      await MessageArchive.create(
+        [
+          {
+            ...data,
+            actionCd: action.actionCd,
+            archivedBy: user._id,
+            archivedAt: /* @__PURE__ */ new Date(),
+            actionAttemptId,
+            actionNotificationState: notificationState,
+            actionNotificationError: null,
+            actionNotificationAttemptedAt: null
+          }
+        ],
+        session2 ? { session: session2, ordered: true } : void 0
+      );
+      const deleted = await Message.deleteOne(
+        { _id: messageId, actionState: "processing", actionAttemptId },
+        session2 ? { session: session2 } : void 0
+      );
+      if ((deleted.deletedCount ?? deleted.n ?? 0) !== 1) {
+        throw new ActionConflictError(String(messageId));
+      }
+    };
+    const startSession = Message.db?.startSession;
+    if (!startSession) {
+      await operation();
+      return;
+    }
+    const session = await startSession.call(Message.db);
+    try {
+      await session.withTransaction(async () => {
+        await operation(session);
+      });
+    } catch (error) {
+      if (this.isTransactionSupportError(error)) {
+        await this.markActionRetryable(messageId, actionAttemptId, error, message);
+        throw new MessageTransactionRequiredError(error);
+      }
+      await this.markActionRetryable(messageId, actionAttemptId, error, message);
+      throw error;
+    } finally {
+      await session.endSession();
+    }
+  }
+  async markActionNotificationState(messageId, actionAttemptId, state, error, sourceDocument) {
+    const MessageArchive = this.resolveModel("archive", sourceDocument);
+    await MessageArchive.updateOne(
+      { _id: messageId, actionAttemptId },
+      {
+        $set: {
+          actionNotificationState: state,
+          actionNotificationError: state === "failed" ? error instanceof Error ? error.message : String(error) : null,
+          actionNotificationAttemptedAt: /* @__PURE__ */ new Date()
+        }
+      }
+    );
+  }
   async runSenderNotification(action, ctx, message) {
     if (!action.senderNotification) return;
     let content;
@@ -645,70 +1388,212 @@ var MessageService = class {
     };
     const documents = !isString(content) ? content.documents || [] : [];
     if (message.fromUser) {
-      await this.createNotification({
-        toUser: message.fromUser,
-        receiverContent: senderNotificationContent,
-        documents
-      });
+      await this.createNotification(
+        {
+          toUser: message.fromUser,
+          receiverContent: senderNotificationContent,
+          documents
+        },
+        message
+      );
+    }
+  }
+  normalizeClientRequestId(clientRequestId) {
+    if (clientRequestId === void 0) {
+      return void 0;
     }
+    if (typeof clientRequestId !== "string") {
+      throw new InvalidClientRequestIdError("clientRequestId must be a string when provided");
+    }
+    const trimmed = clientRequestId.trim();
+    if (trimmed.length === 0) {
+      throw new InvalidClientRequestIdError("clientRequestId must be a non-empty string after trimming whitespace");
+    }
+    if (trimmed.length > MAX_CLIENT_REQUEST_ID_LENGTH) {
+      throw new InvalidClientRequestIdError(
+        `clientRequestId must be at most ${MAX_CLIENT_REQUEST_ID_LENGTH} characters`
+      );
+    }
+    return trimmed;
   }
-  async findByClientRequestId(clientRequestId) {
-    const Message = this.getModel(MESSAGE_MODEL_NAME);
-    const docs = await Message.find({ clientRequestId }).sort({ createdAt: 1, _id: 1 }).limit(Number.MAX_SAFE_INTEGER);
-    return docs.length > 0 ? docs : null;
+  validatePositiveIntegerOption(name, value) {
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+      throw new InvalidPaginationValueError(`${name} must be a finite integer`);
+    }
+    if (value < 1) {
+      throw new InvalidPaginationValueError(`${name} must be at least 1`);
+    }
+    return value;
   }
-  async waitForClientRequestOutcome(clientRequestId) {
-    for (let attempt = 0; attempt < CLIENT_REQUEST_BATCH_RETRY_COUNT; attempt++) {
-      const docs2 = await this.findByClientRequestId(clientRequestId);
-      if (docs2) {
-        return docs2;
-      }
-      const reservation2 = await this.findClientRequestReservation(clientRequestId);
-      if (!reservation2) {
-        return null;
+  normalizeListLimit(value) {
+    if (value === void 0) {
+      return this.defaultListLimit;
+    }
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+      throw new InvalidPaginationValueError("listMessages limit must be a finite integer");
+    }
+    return Math.min(Math.max(value, 1), this.maxListLimit);
+  }
+  normalizeListSkip(value) {
+    if (value === void 0) {
+      return 0;
+    }
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+      throw new InvalidPaginationValueError("listMessages skip must be a finite integer");
+    }
+    return Math.max(value, 0);
+  }
+  buildClientRequestScope(clientRequestId, user, templateCd) {
+    return {
+      clientRequestId,
+      clientRequestOwnerId: this.requireUserId(user),
+      templateCd
+    };
+  }
+  requireUserId(user) {
+    if (!user || user._id === void 0 || user._id === null) {
+      throw new InvalidMessageUserError();
+    }
+    if (typeof user._id === "string") {
+      const id = user._id.trim();
+      if (id.length === 0) {
+        throw new InvalidMessageUserError();
       }
-      if (reservation2.state === "completed") {
-        return [];
+      return id;
+    }
+    if (user._id instanceof mongoose5.Types.ObjectId) {
+      return String(user._id);
+    }
+    throw new InvalidMessageUserError();
+  }
+  async findByClientRequestScope(scope) {
+    const Message = this.resolveModel("active");
+    const docs = await Message.find(scope).sort({ clientRequestItemIndex: 1, _id: 1 }).limit(Number.MAX_SAFE_INTEGER);
+    return docs;
+  }
+  async findCompletedClientRequestReplay(scope) {
+    const reservation = await this.findClientRequestReservation(scope);
+    const docs = await this.findByClientRequestScope(scope);
+    if (!reservation) {
+      if (docs.length > 0) {
+        throw new ClientRequestInconsistentStateError(scope.clientRequestId, "messages exist without a reservation");
       }
-      await this.delay(CLIENT_REQUEST_BATCH_RETRY_DELAY_MS);
+      return null;
     }
-    const docs = await this.findByClientRequestId(clientRequestId);
-    if (docs) {
-      return docs;
+    if (reservation.state === "failed") {
+      throw new ClientRequestFailedError(scope.clientRequestId, reservation.failureMessage);
     }
-    const reservation = await this.findClientRequestReservation(clientRequestId);
-    if (reservation?.state === "completed") {
+    if (reservation.state !== "completed") {
+      return null;
+    }
+    if (reservation.itemCount === null || reservation.itemCount < 0 || !Number.isInteger(reservation.itemCount)) {
+      throw new ClientRequestInconsistentStateError(
+        scope.clientRequestId,
+        "completed reservation has an invalid itemCount"
+      );
+    }
+    if (reservation.itemCount === 0) {
+      if (docs.length > 0) {
+        throw new ClientRequestInconsistentStateError(
+          scope.clientRequestId,
+          "completed zero-item reservation has messages"
+        );
+      }
       return [];
     }
-    return null;
+    const indexes = new Set(docs.map((doc) => doc.clientRequestItemIndex));
+    const hasExpectedIndexes = docs.length === reservation.itemCount && indexes.size === reservation.itemCount && Array.from({ length: reservation.itemCount }, (_, index) => indexes.has(index)).every(Boolean);
+    if (!hasExpectedIndexes) {
+      throw new ClientRequestInconsistentStateError(
+        scope.clientRequestId,
+        `completed reservation expects item indexes 0..${reservation.itemCount - 1} but found ${JSON.stringify(
+          Array.from(indexes)
+        )}`
+      );
+    }
+    return docs;
   }
-  async tryCreateClientRequestReservation(clientRequestId) {
-    const MessageRequest = this.getModel(MESSAGE_REQUEST_MODEL_NAME);
+  async acquireClientRequestStart(scope) {
+    const deadline = Date.now() + this.clientRequestWaitMs;
+    while (true) {
+      const lease = await this.tryAcquireClientRequestLease(scope);
+      if (lease) {
+        return { kind: "lease", lease };
+      }
+      const replay = await this.findCompletedClientRequestReplay(scope);
+      if (replay !== null) {
+        return { kind: "replay", replay };
+      }
+      if (Date.now() >= deadline) {
+        throw new ClientRequestPendingError(scope.clientRequestId);
+      }
+      await this.clientRequestDelay(Math.min(this.clientRequestPollMs, Math.max(deadline - Date.now(), 0)));
+    }
+  }
+  async tryAcquireClientRequestLease(scope) {
+    const created = await this.tryCreateClientRequestReservation(scope);
+    if (created) return created;
+    return this.tryTakeOverStaleClientRequestReservation(scope);
+  }
+  async tryCreateClientRequestReservation(scope) {
+    const MessageRequest = this.resolveModel("request");
+    const ownerId = randomUUID();
     try {
-      await MessageRequest.create({ clientRequestId, state: "pending", itemCount: null });
-      return true;
+      await MessageRequest.create({
+        ...scope,
+        state: "pending",
+        itemCount: null,
+        leaseOwnerId: ownerId,
+        leaseExpiresAt: new Date(Date.now() + this.clientRequestLeaseMs)
+      });
+      return { ownerId };
     } catch (error) {
       if (this.isDuplicateKeyError(error)) {
-        return false;
+        return null;
       }
       throw error;
     }
   }
-  async findClientRequestReservation(clientRequestId) {
-    const MessageRequest = this.getModel(MESSAGE_REQUEST_MODEL_NAME);
-    return await MessageRequest.findOne({ clientRequestId });
+  async tryTakeOverStaleClientRequestReservation(scope) {
+    const MessageRequest = this.resolveModel("request");
+    const ownerId = randomUUID();
+    const reservation = await MessageRequest.findOneAndUpdate(
+      { ...scope, state: "pending", leaseExpiresAt: { $lte: /* @__PURE__ */ new Date() } },
+      {
+        $set: {
+          leaseOwnerId: ownerId,
+          leaseExpiresAt: new Date(Date.now() + this.clientRequestLeaseMs)
+        }
+      },
+      { returnDocument: "after" }
+    );
+    return reservation ? { ownerId } : null;
   }
-  async completeClientRequestReservation(clientRequestId, itemCount) {
-    const MessageRequest = this.getModel(MESSAGE_REQUEST_MODEL_NAME);
-    await MessageRequest.updateOne({ clientRequestId }, { state: "completed", itemCount });
+  async findClientRequestReservation(scope) {
+    const MessageRequest = this.resolveModel("request");
+    return await MessageRequest.findOne(scope);
   }
-  async releaseClientRequestReservation(clientRequestId) {
-    const MessageRequest = this.getModel(MESSAGE_REQUEST_MODEL_NAME);
-    await MessageRequest.deleteOne({ clientRequestId });
+  async failClientRequestReservation(scope, lease, error) {
+    const MessageRequest = this.resolveModel("request");
+    await MessageRequest.updateOne(
+      { ...scope, state: "pending", leaseOwnerId: lease.ownerId },
+      {
+        $set: {
+          state: "failed",
+          failedAt: /* @__PURE__ */ new Date(),
+          failureMessage: error instanceof Error ? error.message : String(error),
+          leaseExpiresAt: null
+        }
+      }
+    );
   }
   isDuplicateKeyError(error) {
     return error instanceof Error && "code" in error && error.code === DUPLICATE_KEY_ERROR_CODE;
   }
+  isTransactionSupportError(error) {
+    if (!(error instanceof Error)) return false;
+    return error.message.includes("Transaction numbers are only allowed") || error.message.includes("Transaction is not supported") || error.message.includes("transactions are not supported");
+  }
   delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
@@ -737,10 +1622,45 @@ var MessageService = class {
 // src/route-factory.ts
 import JsonRouter from "@web-ts-toolkit/express-json-router";
 var ACTION_CD_PATTERN = /^[a-zA-Z0-9_-]+$/;
+var ROUTE_CODE_PATTERN = /^[a-zA-Z0-9_.-]+$/;
+var OBJECT_ID_PATTERN = /^[a-fA-F0-9]{24}$/;
+var MAX_ROUTE_CODE_LENGTH = 128;
+var MAX_CLIENT_REQUEST_ID_LENGTH2 = 128;
+function assertRouteCode(value, name) {
+  if (typeof value !== "string" || value.length === 0 || value.length > MAX_ROUTE_CODE_LENGTH || !ROUTE_CODE_PATTERN.test(value)) {
+    throw new JsonRouter.clientErrors.BadRequestError(
+      `${name} must be a non-empty string of at most ${MAX_ROUTE_CODE_LENGTH} letters, digits, dots, underscores, and hyphens`
+    );
+  }
+}
 function assertValidActionCd(actionCd) {
-  if (typeof actionCd !== "string" || !ACTION_CD_PATTERN.test(actionCd)) {
+  if (typeof actionCd !== "string" || actionCd.length === 0 || actionCd.length > MAX_ROUTE_CODE_LENGTH || !ACTION_CD_PATTERN.test(actionCd)) {
     throw new JsonRouter.clientErrors.BadRequestError(
-      "actionCd must be a string of letters, digits, underscores, and hyphens"
+      `actionCd must be a non-empty string of at most ${MAX_ROUTE_CODE_LENGTH} letters, digits, underscores, and hyphens`
+    );
+  }
+}
+function assertValidMessageId(id) {
+  if (typeof id !== "string" || !OBJECT_ID_PATTERN.test(id)) {
+    throw new JsonRouter.clientErrors.BadRequestError("id must be a 24-character hex ObjectId");
+  }
+}
+function assertValidClientRequestId(clientRequestId) {
+  if (clientRequestId === void 0) {
+    return;
+  }
+  if (typeof clientRequestId !== "string") {
+    throw new JsonRouter.clientErrors.BadRequestError("clientRequestId must be a string when provided");
+  }
+  const trimmed = clientRequestId.trim();
+  if (trimmed.length === 0) {
+    throw new JsonRouter.clientErrors.BadRequestError(
+      "clientRequestId must be a non-empty string after trimming whitespace"
+    );
+  }
+  if (trimmed.length > MAX_CLIENT_REQUEST_ID_LENGTH2) {
+    throw new JsonRouter.clientErrors.BadRequestError(
+      `clientRequestId must be at most ${MAX_CLIENT_REQUEST_ID_LENGTH2} characters`
     );
   }
 }
@@ -749,6 +1669,23 @@ function assertValidUsertype(usertype) {
     throw new JsonRouter.clientErrors.BadRequestError('usertype must be "sender" or "receiver"');
   }
 }
+function assertValidBody(body) {
+  if (body === void 0 || body === null) {
+    return;
+  }
+  if (typeof body !== "object" || Array.isArray(body)) {
+    throw new JsonRouter.clientErrors.BadRequestError("body must be a JSON object");
+  }
+}
+function requireUser(user) {
+  if (!user || user._id === void 0 || user._id === null || String(user._id).trim().length === 0) {
+    throw new JsonRouter.clientErrors.UnauthorizedError("authentication required");
+  }
+  return user;
+}
+function isMongooseCastError(error) {
+  return !!error && typeof error === "object" && error.name === "CastError";
+}
 function mapServiceError(error) {
   if (error instanceof MessageNotFoundError) {
     throw new JsonRouter.clientErrors.NotFoundError("message not found");
@@ -762,15 +1699,34 @@ function mapServiceError(error) {
   if (error instanceof ActionNotAllowedError) {
     throw new JsonRouter.clientErrors.ForbiddenError(error.message);
   }
+  if (error instanceof ActionConflictError) {
+    throw new JsonRouter.clientErrors.ConflictError(error.message);
+  }
+  if (error instanceof ActionRetryableError) {
+    throw new JsonRouter.clientErrors.ConflictError(error.message);
+  }
   if (error instanceof MessageArchivedError) {
     throw new JsonRouter.clientErrors.GoneError(error.message);
   }
+  if (error instanceof InvalidClientRequestIdError) {
+    throw new JsonRouter.clientErrors.BadRequestError(error.message);
+  }
+  if (error instanceof InvalidMessageUserError) {
+    throw new JsonRouter.clientErrors.UnauthorizedError("authentication required");
+  }
+  if (error instanceof ClientRequestPendingError || error instanceof ClientRequestFailedError) {
+    throw new JsonRouter.clientErrors.ConflictError(error.message);
+  }
+  if (isMongooseCastError(error)) {
+    throw new JsonRouter.clientErrors.BadRequestError("id must be a valid ObjectId");
+  }
   throw error;
 }
 function createMessageRoutes(options) {
   const {
     getModel,
     paymentProvider = null,
+    onPaymentCompensationFailure,
     adminRoles,
     registry,
     authMiddleware = [],
@@ -779,17 +1735,20 @@ function createMessageRoutes(options) {
     getIdentity = defaultGetIdentity,
     adminPermissionKey = "is.admin"
   } = options;
-  const service = new MessageService({ getModel, paymentProvider, adminRoles, registry });
+  const service = new MessageService({ getModel, paymentProvider, onPaymentCompensationFailure, adminRoles, registry });
   const router = new JsonRouter("", authMiddleware);
   router.post("/new/:templateCd", async (req) => {
     const templateCd = req.params.templateCd;
-    const user = getUser(req) || { _id: "" };
+    const user = requireUser(getUser(req));
+    assertRouteCode(templateCd, "templateCd");
+    assertValidBody(req.body);
     const roles = user.roles || [];
     const identity = getIdentity(req);
     const permissions = getPermissions(req);
     const body = req.body || {};
     const { clientRequestId, ...payload } = body;
-    const clientRequestIdStr = typeof clientRequestId === "string" ? clientRequestId : void 0;
+    const hasClientRequestId = Object.prototype.hasOwnProperty.call(body, "clientRequestId");
+    assertValidClientRequestId(hasClientRequestId ? clientRequestId : void 0);
     try {
       return await service.createMessage({
         templateCd,
@@ -800,7 +1759,7 @@ function createMessageRoutes(options) {
         payload,
         payerUser: user,
         req,
-        clientRequestId: clientRequestIdStr
+        clientRequestId: hasClientRequestId ? clientRequestId : void 0
       });
     } catch (error) {
       mapServiceError(error);
@@ -809,11 +1768,17 @@ function createMessageRoutes(options) {
   router.get("/:id/actions/:usertype", async (req) => {
     const id = req.params.id;
     const usertype = req.params.usertype;
+    const user = requireUser(getUser(req));
+    assertValidMessageId(id);
     assertValidUsertype(usertype);
     const permissions = getPermissions(req);
     const isAdmin = !!permissions[adminPermissionKey];
-    const user = getUser(req) || { _id: "" };
-    const result = await service.getActions(id, usertype, { permissions, user, isAdmin });
+    let result;
+    try {
+      result = await service.getActions(id, usertype, { permissions, user, isAdmin });
+    } catch (error) {
+      mapServiceError(error);
+    }
     if (!result) {
       throw new JsonRouter.clientErrors.NotFoundError("message not found");
     }
@@ -822,6 +1787,8 @@ function createMessageRoutes(options) {
   async function handleAction(req) {
     const id = req.params.id;
     const actionCd = req.params.actionCd;
+    const user = requireUser(getUser(req));
+    assertValidMessageId(id);
     assertValidActionCd(actionCd);
     let message;
     try {
@@ -829,15 +1796,16 @@ function createMessageRoutes(options) {
     } catch (error) {
       mapServiceError(error);
     }
-    const user = getUser(req) || { _id: "" };
     const permissions = getPermissions(req);
     try {
       return await service.handleAction(message.templateCd, actionCd, { message, user, permissions, req });
     } catch (error) {
+      if (error instanceof ActionNotificationPendingError) {
+        return new JsonRouter.success.Accepted({ message: error.message, actionAttemptId: error.actionAttemptId });
+      }
       mapServiceError(error);
     }
   }
-  router.get("/:id/action/:actionCd", handleAction);
   router.post("/:id/action/:actionCd", handleAction);
   return { router, service };
 }
@@ -852,24 +1820,38 @@ function defaultGetIdentity(req) {
   return req._identity || {};
 }
 export {
+  ActionConflictError,
   ActionNotAllowedError,
   ActionNotFoundError,
+  ActionNotificationPendingError,
+  ActionRetryableError,
+  ActionTemplateMismatchError,
   BaseMessageFields,
+  ClientRequestFailedError,
+  ClientRequestInconsistentStateError,
+  ClientRequestPendingError,
   GENERIC_NOTIFICATION_TEMPLATE_CD,
+  InvalidClientRequestIdError,
+  InvalidMessageUserError,
+  InvalidPaginationValueError,
   MESSAGE_ARCHIVE_MODEL_NAME,
   MESSAGE_MODEL_NAME,
   MESSAGE_REQUEST_MODEL_NAME,
   MessageArchiveSchema,
   MessageArchivedError,
   MessageContentSchema,
+  MessageModelResolutionError,
   MessageNotFoundError,
   MessageRequestSchema,
   MessageSchema,
   MessageService,
+  MessageTransactionRequiredError,
   NoopEmailProvider,
   NoopPaymentProvider,
+  PaymentSessionCompensationError,
   TemplateNotFoundError,
   TemplateRegistry,
+  TemplateRegistryValidationError,
   buildMessageArchiveSchema,
   buildMessageRequestSchema,
   buildMessageSchema,