@web-ts-toolkit/message-service 0.43.0 → 0.47.1

package/index.mjs

@@ -33,6 +33,7 @@ var BaseMessageFields = {
   actionState: { type: String, enum: ["active", "processing", "retryable"], default: "active" },
   actionCd: { type: String, default: null },
   actionAttemptId: { type: String, default: null },
+  actionOwnerToken: { type: String, default: null },
   actionClaimedBy: { type: String, default: null },
   actionClaimedAt: { type: Date, default: null },
   actionLeaseExpiresAt: { type: Date, default: null },
@@ -40,7 +41,7 @@ var BaseMessageFields = {
 };
 
 // src/schemas/message.ts
-import mongoose2 from "mongoose";
+import mongoose3 from "mongoose";
 
 // src/runtime-contract.ts
 var ERROR_BRAND_PREFIX = "@web-ts-toolkit/message-service/error/";
@@ -133,6 +134,9 @@ var TemplateRegistry = class {
   }
   /**
    * Register a template. Overwrites if templateCd already exists.
+   *
+   * Takes an author-friendly mutable `MessageTemplate`; the registry stores a
+   * frozen shallow snapshot (see `RegisteredMessageTemplate`).
    */
   register(template) {
     validateTemplate(template);
@@ -148,6 +152,11 @@ var TemplateRegistry = class {
   }
   /**
    * Find a template by its templateCd.
+   *
+   * Returns a readonly `RegisteredMessageTemplate` view matching the registry
+   * freeze depth (top-level, content objects, object uiTemplates, the action
+   * array, and each action plus its confirmation/payload are frozen).
+   * Mutating the result throws at runtime; register a replacement instead.
    */
   find(templateCd) {
     return this.templates.get(templateCd);
@@ -166,6 +175,8 @@ var TemplateRegistry = class {
   }
   /**
    * Get all registered templates.
+   *
+   * Returns readonly `RegisteredMessageTemplate` views; see `find()`.
    */
   getAll() {
     return Array.from(this.templates.values());
@@ -193,6 +204,7 @@ function includesAction(templateCd, actionCd, registry) {
 }
 
 // src/schemas/methods.ts
+import { Types } from "mongoose";
 function isSender(user) {
   const fromUser = normalizeStoredUserId(this.fromUser);
   const userId = normalizeMessageUserId(user);
@@ -204,450 +216,131 @@ function isReceiver(user) {
   return toUser !== null && userId !== null && toUser === userId || this.toRoles.some((r) => user.roles?.includes(r));
 }
 function normalizeMessageUserId(user) {
-  return normalizeStoredUserId(user?._id ?? null);
+  return normalizeId(user?._id);
 }
 function normalizeStoredUserId(value) {
-  if (value === null || value === void 0) return null;
+  if (value instanceof Types.ObjectId) return value.toHexString();
+  if (value !== null && typeof value === "object") {
+    return normalizeId(value._id);
+  }
+  return normalizeId(value);
+}
+function normalizeId(value) {
   if (typeof value === "string") {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : null;
   }
-  return String(value);
+  return value instanceof Types.ObjectId ? value.toHexString() : null;
 }
 
-// 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`
-    );
+// src/errors.ts
+var TRANSACTION_REQUIRED_MESSAGE = "message-service requires MongoDB replica set or sharded-cluster transactions for idempotent batch creation";
+var MessageNotFoundError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "MessageNotFoundError");
   }
-  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;
+  constructor(messageId) {
+    super(`message "${messageId}" not found`);
+    this.name = "MessageNotFoundError";
+    markRuntimeError(this, this.name);
   }
-}
-function createArchiveMethod(ctx) {
-  return function archive(actionCd, archivedBy, registry) {
-    if (!includesAction(this.templateCd, actionCd, registry) || !archivedBy) {
-      return Promise.resolve();
-    }
-    const MessageArchive = resolveDocumentModel(this, ctx.archiveModelName, "archive");
-    const data = this.toObject();
-    return MessageArchive.create({
-      ...data,
-      actionCd,
-      archivedBy
-    }).then(async () => {
-      await this.deleteOne();
-    });
-  };
-}
-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 (!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 {
-      await ctx.emailNotifier(user.email, title, body);
-    } catch (error) {
-      await reportEmailFailure(ctx, "notifier", error, this, title);
-    }
-  };
-}
-async function reportEmailFailure(ctx, stage, error, message, title) {
-  try {
-    await ctx.onEmailDeliveryFailure?.({
-      stage,
-      error,
-      messageId: message._id,
-      recipientId: message.toUser,
-      title
-    });
-  } catch {
+};
+var MessageArchivedError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "MessageArchivedError");
   }
-}
-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 on Mongoose connection "${connectionName}". Register the model on that connection before buildMessageSchema().`
-    );
+  constructor(messageId) {
+    super(`message "${messageId}" is archived`);
+    this.name = "MessageArchivedError";
+    markRuntimeError(this, this.name);
   }
-}
-function resolveConfig(config) {
-  return {
-    emailNotifier: config?.emailNotifier ?? null,
-    onEmailDeliveryFailure: config?.onEmailDeliveryFailure,
-    emailNotificationExclusions: (config?.emailNotificationExclusions ?? []).map(normalizeEmailTitle),
-    userModelName: config?.userModelName ?? "User",
-    archiveModelName: config?.archiveModelName ?? MESSAGE_ARCHIVE_MODEL_NAME,
-    connection: config?.connection ?? mongoose2
-  };
-}
-function buildMessageSchema(config) {
-  const resolved = resolveConfig(config);
-  if (resolved.emailNotifier) {
-    assertModelRegistered(resolved.connection, resolved.userModelName, "user");
+};
+var TemplateNotFoundError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "TemplateNotFoundError");
   }
-  const schema = new mongoose2.Schema(BaseMessageFields, {
-    timestamps: 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(
-    { 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" }
-      }
+  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;
     }
-  );
-  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" }
-      }
-    }
-  );
-  schema.methods.isSender = isSender;
-  schema.methods.isReceiver = isReceiver;
-  schema.methods.archive = createArchiveMethod({ archiveModelName: resolved.archiveModelName });
-  if (resolved.emailNotifier) {
-    schema.pre("save", createEmailStateCaptureHook());
-    schema.post(
-      "save",
-      createPostSaveEmailHook({
-        emailNotifier: resolved.emailNotifier,
-        onEmailDeliveryFailure: resolved.onEmailDeliveryFailure,
-        emailNotificationExclusions: resolved.emailNotificationExclusions,
-        userModelName: resolved.userModelName
-      })
-    );
-  }
-  return schema;
-}
-var MessageSchema = buildMessageSchema();
-
-// src/schemas/message-archive.ts
-import mongoose3 from "mongoose";
-function buildMessageArchiveSchema() {
-  const schema = new mongoose3.Schema(
-    {
-      ...BaseMessageFields,
-      actionCd: { type: String, default: "" },
-      archivedBy: { type: mongoose3.Schema.Types.ObjectId, default: null, index: true },
-      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
-    }
-  );
-  schema.index({ createdAt: 1 });
-  schema.methods.isSender = isSender;
-  schema.methods.isReceiver = isReceiver;
-  return schema;
-}
-var MessageArchiveSchema = buildMessageArchiveSchema();
-
-// src/schemas/message-request.ts
-import mongoose4 from "mongoose";
-function buildMessageRequestSchema() {
-  const schema = new mongoose4.Schema(
-    {
-      clientRequestId: { type: String, required: true },
-      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({ clientRequestOwnerId: 1, templateCd: 1, clientRequestId: 1 }, { unique: true });
-  schema.index({ updatedAt: 1 });
-  schema.index({ state: 1, leaseExpiresAt: 1 });
-  return schema;
-}
-var MessageRequestSchema = buildMessageRequestSchema();
-
-// src/template-engine.ts
-import Handlebars from "handlebars";
-var compiledTemplates = /* @__PURE__ */ new Map();
-function compile(template, data) {
-  let compiled = compiledTemplates.get(template);
-  if (!compiled) {
-    compiled = Handlebars.compile(template, { noEscape: true });
-    compiledTemplates.set(template, compiled);
-  }
-  return compiled(data);
-}
-function filterActions(actions, usertype, options = {}) {
-  const { permissions = {}, message = {}, data = {} } = options;
-  return actions.filter((action) => {
-    if (!action[usertype]) return false;
-    if (action.permission && !permissions[action.permission]) return false;
-    if (action.condition && !action.condition(message)) return false;
-    return true;
-  }).map((action) => {
-    const { confirmation } = action;
-    return {
-      actionCd: action.actionCd,
-      isDefault: action.isDefault,
-      name: compile(action.name, data),
-      variant: action.variant,
-      confirmation: confirmation ? {
-        title: compile(confirmation.title, data),
-        message: compile(confirmation.message, data),
-        ...confirmation.notesLabel ? { notesLabel: compile(confirmation.notesLabel, data) } : {},
-        ...confirmation.requireNotes !== void 0 ? { requireNotes: confirmation.requireNotes } : {},
-        ...confirmation.documents !== void 0 ? { documents: confirmation.documents } : {}
-      } : void 0,
-      payload: action.payload
-    };
-  });
-}
-function isActionAllowed(action, user, message, options = {}) {
-  const isReceiver2 = action.receiver && message.isReceiver(user);
-  const isSender2 = action.sender && message.isSender(user);
-  if (!isReceiver2 && !isSender2) return false;
-  if (action.permission && !(options.permissions || {})[action.permission]) return false;
-  if (action.condition && !action.condition(message)) return false;
-  return true;
-}
-function interpolateTemplate(template, data, usertype, options = {}) {
-  const { permissions = {}, message = {} } = options;
-  const { senderContent, receiverContent, actions, uiTemplate } = template;
-  return {
-    senderContent: {
-      title: compile(senderContent?.title || "", data),
-      long: compile(senderContent?.long || "", data),
-      short: compile(senderContent?.short || "", data)
-    },
-    receiverContent: {
-      title: compile(receiverContent?.title || "", data),
-      long: compile(receiverContent?.long || "", data),
-      short: compile(receiverContent?.short || "", data)
-    },
-    uiTemplate: resolveUiTemplate(uiTemplate, usertype),
-    actions: filterActions(actions, usertype, { permissions, message, data })
-  };
-}
-function resolveUiTemplate(uiTemplate, usertype) {
-  if (typeof uiTemplate === "string") return uiTemplate;
-  return uiTemplate[usertype] || uiTemplate.sender || uiTemplate.receiver || "";
-}
-
-// src/providers/email.ts
-var NoopEmailProvider = class {
-  async sendNotification(_to, _title, _body) {
-  }
-};
-
-// src/providers/payment.ts
-var NoopPaymentProvider = class {
-  async createSession(_user, _code, _priceArgs) {
-    return null;
-  }
-  async expireSession(_sessionId) {
-  }
-  async refundPayment(_sessionId) {
-  }
-};
-
-// 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_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 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;
     }
   }
 };
@@ -671,6 +364,16 @@ var InvalidPaginationValueError = class extends Error {
     markRuntimeError(this, this.name);
   }
 };
+var InvalidMessageServiceOptionError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "InvalidMessageServiceOptionError");
+  }
+  constructor(message) {
+    super(message);
+    this.name = "InvalidMessageServiceOptionError";
+    markRuntimeError(this, this.name);
+  }
+};
 var ClientRequestPendingError = class extends Error {
   static [Symbol.hasInstance](value) {
     return isRuntimeError(value, "ClientRequestPendingError");
@@ -688,9 +391,14 @@ var ClientRequestFailedError = class extends Error {
     return isRuntimeError(value, "ClientRequestFailedError");
   }
   constructor(clientRequestId, reason) {
-    super(`clientRequestId "${clientRequestId}" previously failed${reason ? `: ${reason}` : ""}`);
+    super(`clientRequestId "${clientRequestId}" previously failed; retry with a new clientRequestId`);
     this.name = "ClientRequestFailedError";
     markRuntimeError(this, this.name);
+    this.clientRequestId = clientRequestId;
+    this.failureReason = reason ?? null;
+    if (reason != null) {
+      this.cause = reason;
+    }
   }
 };
 var ClientRequestInconsistentStateError = class extends Error {
@@ -734,7 +442,7 @@ var MessageModelResolutionError = class extends Error {
 };
 var PaymentSessionCompensationError = class extends Error {
   static [Symbol.hasInstance](value) {
-    return isRuntimeError(value, "PaymentSessionCompensationError");
+    return isRuntimeError(value, "PaymentSessionCompensationError") || isRuntimeError(value, "PaymentSessionCompensationAggregateError");
   }
   constructor(sessionId, operation, compensationError, originalError, hookError) {
     super(`payment session compensation failed for session "${sessionId}" during ${operation}`);
@@ -748,6 +456,202 @@ var PaymentSessionCompensationError = class extends Error {
     this.cause = compensationError;
   }
 };
+var PaymentSessionCompensationAggregateError = class extends PaymentSessionCompensationError {
+  static [Symbol.hasInstance](value) {
+    return isRuntimeError(value, "PaymentSessionCompensationAggregateError");
+  }
+  constructor(failures, originalError) {
+    const first = failures[0];
+    super(first.sessionId, "expire", first.compensationError, originalError, first.hookError);
+    this.name = "PaymentSessionCompensationAggregateError";
+    markRuntimeError(this, this.name);
+    this.failures = failures;
+    if (failures.length > 1) {
+      this.message = `payment session compensation failed for ${failures.length} sessions (${failures.map((f) => `"${f.sessionId}"`).join(", ")}) during expire`;
+    }
+  }
+};
+
+// src/persistence.ts
+function isDuplicateKeyError(error) {
+  return error instanceof Error && "code" in error && error.code === 11e3;
+}
+function 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");
+}
+async function runMessageTransaction(activeModel, operation, options) {
+  const startSession = activeModel.db?.startSession;
+  if (!options.session && typeof startSession !== "function") {
+    throw new MessageTransactionRequiredError(
+      new Error("message-service: atomic lifecycle write requires a Mongoose model with db.startSession support")
+    );
+  }
+  let session;
+  try {
+    session = options.session ?? await startSession.call(activeModel.db);
+  } catch (error) {
+    throw isTransactionSupportError(error) ? new MessageTransactionRequiredError(error) : error;
+  }
+  let committed = false;
+  let originalError;
+  let operationFailure;
+  try {
+    let result;
+    await session.withTransaction(async () => {
+      operationFailure = void 0;
+      try {
+        result = await operation(session);
+      } catch (error) {
+        operationFailure = { error };
+        throw error;
+      }
+    });
+    committed = true;
+    return result;
+  } catch (error) {
+    const primary = operationFailure ? operationFailure.error : error;
+    originalError = isTransactionSupportError(primary) ? new MessageTransactionRequiredError(primary) : primary;
+    throw originalError;
+  } finally {
+    if (!options.session) {
+      try {
+        await session.endSession();
+      } catch (error) {
+        const event = {
+          operation: options.operation,
+          stage: "endSession",
+          error,
+          ...committed ? { outcome: "committed" } : { outcome: "failed", originalError }
+        };
+        try {
+          await options.onTransactionCleanupFailure?.(event);
+        } catch {
+        }
+      }
+    }
+  }
+}
+
+// src/message-service.ts
+import { isString } from "@web-ts-toolkit/utils";
+import { randomUUID } from "crypto";
+import mongoose2 from "mongoose";
+
+// src/template-engine.ts
+import Handlebars from "handlebars";
+var compiledTemplates = /* @__PURE__ */ new Map();
+function compile(template, data) {
+  let compiled = compiledTemplates.get(template);
+  if (!compiled) {
+    compiled = Handlebars.compile(template, { noEscape: true });
+    compiledTemplates.set(template, compiled);
+  }
+  return compiled(data);
+}
+function hasExplicitPermissionGrant(permissions, key) {
+  if (!permissions || typeof permissions !== "object" || Array.isArray(permissions)) return false;
+  if (typeof key !== "string" || key.length === 0) return false;
+  if (!Object.prototype.hasOwnProperty.call(permissions, key)) return false;
+  return permissions[key] === true;
+}
+function interpolateMessageContent(template, data) {
+  const { senderContent, receiverContent } = template;
+  return {
+    senderContent: {
+      title: compile(senderContent?.title || "", data),
+      long: compile(senderContent?.long || "", data),
+      short: compile(senderContent?.short || "", data)
+    },
+    receiverContent: {
+      title: compile(receiverContent?.title || "", data),
+      long: compile(receiverContent?.long || "", data),
+      short: compile(receiverContent?.short || "", data)
+    }
+  };
+}
+function resolveUiTemplate(uiTemplate, usertype) {
+  if (typeof uiTemplate === "string") return uiTemplate;
+  return uiTemplate[usertype] || uiTemplate.sender || uiTemplate.receiver || "";
+}
+function filterActions(actions, usertype, options = {}) {
+  const { permissions = {}, message = {}, data = {} } = options;
+  return actions.filter((action) => {
+    if (!action[usertype]) return false;
+    if (action.permission && !hasExplicitPermissionGrant(permissions, action.permission)) return false;
+    if (action.condition && !action.condition(message)) return false;
+    return true;
+  }).map((action) => {
+    const { confirmation } = action;
+    return {
+      actionCd: action.actionCd,
+      isDefault: action.isDefault,
+      name: compile(action.name, data),
+      variant: action.variant,
+      confirmation: confirmation ? {
+        title: compile(confirmation.title, data),
+        message: compile(confirmation.message, data),
+        ...confirmation.notesLabel ? { notesLabel: compile(confirmation.notesLabel, data) } : {},
+        ...confirmation.requireNotes !== void 0 ? { requireNotes: confirmation.requireNotes } : {},
+        ...confirmation.documents !== void 0 ? { documents: confirmation.documents } : {}
+      } : void 0,
+      payload: action.payload
+    };
+  });
+}
+function isActionAllowed(action, user, message, options = {}) {
+  const isReceiver2 = action.receiver && message.isReceiver(user);
+  const isSender2 = action.sender && message.isSender(user);
+  if (!isReceiver2 && !isSender2) return false;
+  if (action.permission && !hasExplicitPermissionGrant(options.permissions, action.permission)) return false;
+  if (action.condition && !action.condition(message)) return false;
+  return true;
+}
+function interpolateTemplate(template, data, usertype, options = {}) {
+  const { permissions = {}, message = {} } = options;
+  const { actions, uiTemplate } = template;
+  return {
+    ...interpolateMessageContent(template, data),
+    uiTemplate: resolveUiTemplate(uiTemplate, usertype),
+    actions: filterActions(actions, usertype, { permissions, message, data })
+  };
+}
+
+// src/message-service.ts
+var DEFAULT_LIST_LIMIT = 50;
+var MAX_LIST_LIMIT = 100;
+var CLIENT_REQUEST_LEASE_MS = 3e4;
+var CLIENT_REQUEST_WAIT_MS = 5e3;
+var CLIENT_REQUEST_POLL_MS = 200;
+var MAX_MESSAGE_SERVICE_TIMEOUT_MS = 2147483647;
+var ACTION_LEASE_MS = 3e4;
+var MAX_CLIENT_REQUEST_ID_LENGTH = 128;
+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__";
+function isValidMessageUserId(id) {
+  if (typeof id === "string") {
+    return id.trim().length > 0;
+  }
+  if (id instanceof mongoose2.Types.ObjectId) {
+    return true;
+  }
+  return false;
+}
+function requireMessageUserId(user) {
+  if (!user || typeof user !== "object" || Array.isArray(user)) {
+    throw new InvalidMessageUserError();
+  }
+  const id = user._id;
+  if (!isValidMessageUserId(id)) {
+    throw new InvalidMessageUserError();
+  }
+  return typeof id === "string" ? id.trim() : String(id);
+}
 var MessageService = class {
   constructor(options) {
     this.getModel = options.getModel;
@@ -757,6 +661,7 @@ var MessageService = class {
     this.expirePaymentSession = this.paymentProvider?.expireSession.bind(this.paymentProvider);
     this.refundPaymentSession = this.paymentProvider?.refundPayment.bind(this.paymentProvider);
     this.onPaymentCompensationFailure = options.onPaymentCompensationFailure;
+    this.onTransactionCleanupFailure = options.onTransactionCleanupFailure;
     this.adminRoles = options.adminRoles ?? [];
     this.registry = options.registry ?? defaultRegistry;
     this.maxListLimit = this.validatePositiveIntegerOption("maxListLimit", options.maxListLimit ?? MAX_LIST_LIMIT);
@@ -767,10 +672,23 @@ var MessageService = class {
     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.clientRequestLeaseMs = this.validateDurationOption(
+      "clientRequestLeaseMs",
+      options.clientRequestLeaseMs ?? CLIENT_REQUEST_LEASE_MS,
+      1
+    );
+    this.clientRequestWaitMs = this.validateDurationOption(
+      "clientRequestWaitMs",
+      options.clientRequestWaitMs ?? CLIENT_REQUEST_WAIT_MS,
+      0
+    );
+    this.clientRequestPollMs = this.validateDurationOption(
+      "clientRequestPollMs",
+      options.clientRequestPollMs ?? CLIENT_REQUEST_POLL_MS,
+      1
+    );
     this.clientRequestDelay = options.clientRequestDelay ?? this.delay;
+    this.clientRequestNow = options.clientRequestNow ?? (() => Date.now());
     this.actionLeaseMs = ACTION_LEASE_MS;
   }
   // -------------------------------------------------------------------------
@@ -779,6 +697,10 @@ var MessageService = class {
   /**
    * Find a message by id, falling back to the archive. Returns null if
    * the message does not exist in either collection.
+   *
+   * Trusted host-level operation: takes no principal and performs no
+   * user-identity validation. Hosts must authorize the returned document
+   * before exposing it to a user (see `getActions`/`handleAction`).
    */
   async findMessage(messageId, options = {}) {
     const Message = this.resolveModel("active");
@@ -791,6 +713,13 @@ var MessageService = class {
       options
     );
   }
+  /**
+   * Same as `findMessage`, but throws `MessageNotFoundError` when neither the
+   * active nor the archive collection holds the id.
+   *
+   * Trusted host-level operation: no principal validation. Hosts must
+   * authorize before exposing the result to a user.
+   */
   async findMessageOrThrow(messageId, options = {}) {
     const message = await this.findMessage(messageId, options);
     if (!message) {
@@ -801,6 +730,25 @@ var MessageService = class {
   // -------------------------------------------------------------------------
   // Create message from template
   // -------------------------------------------------------------------------
+  /**
+   * Create messages from a trusted template as an authenticated user.
+   *
+   * User-facing entry point: `user` (and `payerUser` when provided) must
+   * carry a valid principal id (non-empty string or ObjectId; numbers,
+   * arrays, and plain objects are rejected with `InvalidMessageUserError`)
+   * before any template, provider, or model effect runs. Both the
+   * idempotent (`clientRequestId`) and direct branches enforce this.
+   *
+   * Idempotent replay contract (MSGF-06): a completed same-scope replay
+   * returns the current active/archive records merged from both collections
+   * (`Array<IMessage | IMessageArchive>`), sorted by exact
+   * `clientRequestItemIndex`, without rerunning preparation/payment. Fresh
+   * creates resolve active documents only. Archive entries are returned as
+   * persisted `IMessageArchive` — never cast to `IMessage` and never given
+   * fabricated active-only methods. Narrow with `'archivedAt' in doc`.
+   * Archive retention bounds the replay window: deleted archive documents
+   * surface as `ClientRequestInconsistentStateError`, not partial replays.
+   */
   async createMessage(params) {
     const {
       templateCd,
@@ -813,6 +761,10 @@ var MessageService = class {
       req,
       clientRequestId
     } = params;
+    this.requireUserId(user);
+    if (payerUser !== void 0) {
+      this.requireUserId(payerUser);
+    }
     const normalizedClientRequestId = this.normalizeClientRequestId(clientRequestId);
     if (normalizedClientRequestId) {
       return this.createMessageWithReservation({
@@ -892,8 +844,13 @@ var MessageService = class {
     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));
+      try {
+        for (let index = 0; index < items.length; index++) {
+          docs.push(await this.buildMessageDocument(template, items[index], ctx, clientRequestScope, index));
+        }
+      } catch (error) {
+        await this.compensatePaymentSessions(docs, error, clientRequestScope);
+        throw error;
       }
       return this.persistPreparedBatchTransaction(clientRequestScope, clientRequestLease, docs);
     }
@@ -907,6 +864,13 @@ var MessageService = class {
   // -------------------------------------------------------------------------
   // Create generic notification (no template, no actions)
   // -------------------------------------------------------------------------
+  /**
+   * Create a generic notification without template preparation or actions.
+   *
+   * Trusted host-level operation: takes raw `UserId` values (string or
+   * ObjectId, including null) and performs no principal validation. Hosts
+   * own authentication/authorization for notification creation.
+   */
   async createNotification(params, sourceDocument) {
     const Message = this.resolveModel("active", sourceDocument);
     return Message.create({
@@ -927,6 +891,8 @@ var MessageService = class {
    * Build a Mongoose filter for messages visible to the given user.
    * Exposed so callers can use the same visibility rules for custom
    * queries (e.g. with `populate`).
+   *
+   * User-facing helper: validates `user` before building the filter.
    */
   buildVisibilityFilter(user) {
     const userId = this.requireUserId(user);
@@ -938,6 +904,9 @@ var MessageService = class {
    * List active (non-archived) messages visible to a user.
    * Returns messages where the user is the sender, the receiver,
    * or matches one of the recipient's roles.
+   *
+   * User-facing operation: validates `user` via the shared principal
+   * contract. Returns `IMessage[]` ordered by `{ createdAt: -1, _id: -1 }`.
    */
   async listMessages(params) {
     const { user, limit: rawLimit, skip: rawSkip, populate } = params;
@@ -953,6 +922,8 @@ var MessageService = class {
   /**
    * Count active (non-archived) messages visible to a user.
    * Useful for badge indicators ("3 new messages").
+   *
+   * User-facing operation: validates `user` via the shared principal contract.
    */
   async countMessages(user) {
     const Message = this.resolveModel("active");
@@ -961,11 +932,32 @@ var MessageService = class {
   // -------------------------------------------------------------------------
   // Get actions for a message
   // -------------------------------------------------------------------------
-  async getActions(messageId, usertype, options = {}) {
-    const message = options.message ?? await this.findMessage(messageId, { populate: options.populate });
-    if (!message) return null;
-    const user = this.requireUserId(options.user);
+  /**
+   * Get available actions for a message as an authenticated user.
+   *
+   * User-facing operation: `options.user` is required and must carry a valid
+   * principal id (non-empty string or ObjectId). It is validated before any
+   * model lookup or template operation; invalid principals throw
+   * `InvalidMessageUserError`.
+   *
+   * Returns `{ uiTemplate, actions }` for visible messages, or `null` when the
+   * message is missing, the user has no sender/receiver relationship (unless
+   * `isAdmin`), or the template is unknown. Admin (`isAdmin`) and archived
+   * views return the resolved `uiTemplate` with an empty action list without
+   * evaluating action `condition` predicates. All listings
+   * read the requested id from the configured store. Relationships are
+   * checked on canonical stored IDs before optional presentation population.
+   * Conditions see that read snapshot with `populate` applied (mutations still
+   * check unpopulated atomic claims); this does not reserve an action or prevent
+   * subsequent host writes. Action labels and
+   * confirmations render from persisted `message.payload` (missing values
+   * render empty), distinct from creation-time `templateData`.
+   */
+  async getActions(messageId, usertype, options) {
+    const user = requireMessageUserId(options?.user);
     const authorizedUser = { ...options.user, _id: user };
+    const message = await this.findMessage(messageId);
+    if (!message) return null;
     if (!options.isAdmin) {
       const isAllowedUsertype = usertype === "sender" ? message.isSender(authorizedUser) : message.isReceiver(authorizedUser);
       if (!isAllowedUsertype) {
@@ -977,31 +969,44 @@ var MessageService = class {
     }
     const template = this.registry.find(message.templateCd);
     if (!template) return null;
+    if (options.isAdmin || this.isArchivedMessage(message)) {
+      return { uiTemplate: resolveUiTemplate(template.uiTemplate, usertype), actions: [] };
+    }
+    if (options.populate) {
+      await message.populate(options.populate);
+    }
     const data = message.payload ?? {};
     const interpolated = interpolateTemplate(template, data, usertype, {
       permissions: options.permissions,
       message
     });
-    if (options.isAdmin || this.isArchivedMessage(message)) {
-      return { uiTemplate: interpolated.uiTemplate, actions: [] };
-    }
     return { uiTemplate: interpolated.uiTemplate, actions: interpolated.actions };
   }
   // -------------------------------------------------------------------------
   // Handle an action on a message
   // -------------------------------------------------------------------------
+  /**
+   * Execute an action with a durable claim, stable handler attempt key,
+   * transactional archive, and post-commit sender notification status.
+   *
+   * User-facing operation: `data.user` is validated before any template or
+   * model effect. Authorization and handler selection bind to the persisted
+   * claim, not the caller-supplied `data.message` copy. Archived messages
+   * are re-read by id on their owning connection and apply a stored
+   * sender/receiver relationship gate before disclosing current attempt IDs
+   * or notification state. A missing archive throws `MessageNotFoundError`.
+   * Returns the handler's value (`unknown`; templates
+   * document their own shape).
+   */
   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 archived = await this.resolveModel("archive", data.message).findById(
+        data.message._id
+      );
+      if (!archived) throw new MessageNotFoundError(String(data.message._id));
+      this.throwArchivedOutcome(archived, authorizedUser);
     }
     if (templateCd !== data.message.templateCd) {
       throw new ActionTemplateMismatchError(data.message.templateCd, templateCd);
@@ -1014,6 +1019,21 @@ var MessageService = class {
       throw new ActionNotAllowedError();
     }
     const claim = await this.claimAction(data.message, actionCd, authorizedUser);
+    let authorizedAction;
+    try {
+      authorizedAction = this.authorizeClaimedAction(templateCd, actionCd, claim.message, authorizedUser, {
+        permissions: data.permissions
+      });
+    } catch (authError) {
+      try {
+        await this.releaseDeniedActionClaim(claim, authError);
+      } catch (releaseError) {
+        if (!(releaseError instanceof ActionConflictError)) {
+          throw releaseError;
+        }
+      }
+      throw authError;
+    }
     const ctx = this.buildActionContext({
       ...data,
       user: authorizedUser,
@@ -1022,24 +1042,44 @@ var MessageService = class {
     });
     let result;
     try {
-      result = await action.runHandler(ctx);
+      result = await authorizedAction.runHandler(ctx);
     } catch (error) {
-      await this.markActionRetryable(data.message._id, claim.actionAttemptId, error, claim.message);
+      await this.markActionRetryable(
+        data.message._id,
+        claim.actionAttemptId,
+        claim.actionOwnerToken,
+        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) {
+    await this.archiveClaimedMessage(
+      claim.message,
+      authorizedAction,
+      authorizedUser,
+      claim.actionAttemptId,
+      claim.actionOwnerToken
+    );
+    if (authorizedAction.senderNotification) {
       try {
-        await this.runSenderNotification(action, ctx, claim.message);
+        await this.runSenderNotification(authorizedAction, ctx, claim.message);
         await this.markActionNotificationState(
           data.message._id,
           claim.actionAttemptId,
+          claim.actionOwnerToken,
           "sent",
           void 0,
           claim.message
         );
       } catch (error) {
-        await this.markActionNotificationState(data.message._id, claim.actionAttemptId, "failed", error, claim.message);
+        await this.markActionNotificationState(
+          data.message._id,
+          claim.actionAttemptId,
+          claim.actionOwnerToken,
+          "failed",
+          error,
+          claim.message
+        );
         throw new ActionNotificationPendingError(String(data.message._id), claim.actionAttemptId, result, error);
       }
     }
@@ -1071,7 +1111,7 @@ var MessageService = class {
       if (this.connection) {
         return this.connection.model(modelName);
       }
-      return mongoose5.model(modelName);
+      return mongoose2.model(modelName);
     } catch (error) {
       throw new MessageModelResolutionError(role, modelName, this.describeModelSource(sourceConnection), error);
     }
@@ -1083,7 +1123,7 @@ var MessageService = class {
         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);
+        return mongoose2.model(name);
       } catch (error) {
         throw new MessageModelResolutionError("user", name, this.describeModelSource(sourceConnection), error);
       }
@@ -1133,7 +1173,7 @@ var MessageService = class {
         );
         if (!paymentSession) throw new Error("payment session creation failed");
       }
-      const interpolated = interpolateTemplate(template, m.templateData || {}, "receiver");
+      const interpolated = interpolateMessageContent(template, m.templateData || {});
       return {
         type,
         templateCd: template.templateCd,
@@ -1159,10 +1199,17 @@ var MessageService = class {
     }
   }
   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) : [];
+    let Message;
+    let MessageRequest;
+    try {
+      Message = this.resolveModel("active");
+      MessageRequest = this.resolveModel("request", void 0, Message);
+    } catch (error) {
+      await this.compensatePaymentSessions(docs, error, scope);
+      throw error;
+    }
+    const operation = async (session) => {
+      const created = docs.length > 0 ? await Message.create(docs, { session, ordered: true }) : [];
       const result = await MessageRequest.updateOne(
         { ...scope, state: "pending", leaseOwnerId: lease.ownerId },
         {
@@ -1173,45 +1220,50 @@ var MessageService = class {
             leaseExpiresAt: null
           }
         },
-        session2 ? { session: session2 } : void 0
+        { session }
       );
       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 await runMessageTransaction(Message, operation, {
+        operation: "createBatch",
+        onTransactionCleanupFailure: this.onTransactionCleanupFailure
       });
-      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();
+      await this.compensatePaymentSessions(docs, error, scope);
+      throw error;
     }
   }
   async compensatePaymentSessions(docs, originalError, scope) {
     const sessionIds = docs.map((doc) => doc.paymentSession).filter((sessionId) => typeof sessionId === "string" && sessionId.length > 0);
+    if (sessionIds.length === 0) return;
+    if (!this.expirePaymentSession) return;
+    const failures = [];
+    let firstSingleError;
     for (const sessionId of sessionIds) {
-      await this.compensatePaymentSession(sessionId, originalError, scope);
+      try {
+        await this.compensatePaymentSession(sessionId, originalError, scope);
+      } catch (error) {
+        if (error instanceof PaymentSessionCompensationError) {
+          if (!firstSingleError) firstSingleError = error;
+          failures.push({
+            sessionId: error.sessionId,
+            compensationError: error.compensationError,
+            hookError: error.hookError
+          });
+        } else {
+          failures.push({ sessionId, compensationError: error });
+        }
+      }
     }
+    if (failures.length === 0) return;
+    if (sessionIds.length === 1 && firstSingleError) {
+      throw firstSingleError;
+    }
+    throw new PaymentSessionCompensationAggregateError(failures, originalError);
   }
   async compensatePaymentSession(sessionId, originalError, scope) {
     if (!this.expirePaymentSession) return;
@@ -1258,14 +1310,28 @@ var MessageService = class {
       actionFailureMessage: null
     };
     const firstAttemptId = randomUUID();
+    const firstOwnerToken = randomUUID();
     const firstClaim = await Message.findOneAndUpdate(
       { _id: messageId, $or: [{ actionState: "active" }, { actionState: null }, { actionState: { $exists: false } }] },
-      { $set: { ...claimBase, actionState: "processing", actionAttemptId: firstAttemptId } },
+      {
+        $set: {
+          ...claimBase,
+          actionState: "processing",
+          actionAttemptId: firstAttemptId,
+          actionOwnerToken: firstOwnerToken
+        }
+      },
       { returnDocument: "after" }
     );
-    if (firstClaim?.actionAttemptId) {
-      return { message: firstClaim, actionAttemptId: firstClaim.actionAttemptId };
+    if (firstClaim?.actionAttemptId && firstClaim?.actionOwnerToken) {
+      return {
+        message: firstClaim,
+        actionAttemptId: firstClaim.actionAttemptId,
+        actionOwnerToken: firstClaim.actionOwnerToken,
+        fresh: true
+      };
     }
+    const nextOwnerToken = randomUUID();
     const retryClaim = await Message.findOneAndUpdate(
       {
         _id: messageId,
@@ -1273,27 +1339,105 @@ var MessageService = class {
         actionAttemptId: { $type: "string" },
         $or: [{ actionState: "retryable" }, { actionState: "processing", actionLeaseExpiresAt: { $lte: now } }]
       },
-      { $set: { ...claimBase, actionState: "processing" } },
+      { $set: { ...claimBase, actionState: "processing", actionOwnerToken: nextOwnerToken } },
       { returnDocument: "after" }
     );
-    if (retryClaim?.actionAttemptId) {
-      return { message: retryClaim, actionAttemptId: retryClaim.actionAttemptId };
+    if (retryClaim?.actionAttemptId && retryClaim?.actionOwnerToken) {
+      return {
+        message: retryClaim,
+        actionAttemptId: retryClaim.actionAttemptId,
+        actionOwnerToken: retryClaim.actionOwnerToken,
+        fresh: false
+      };
+    }
+    const archived = await this.resolveModel("archive", message, Message).findById(
+      messageId
+    );
+    if (archived) {
+      this.throwArchivedOutcome(archived, user);
+    }
+    throw new ActionConflictError(String(messageId));
+  }
+  /**
+   * Relationship/permission policy for archived outcomes.
+   *
+   * Only the recorded sender or receiver may observe whether an archived
+   * message is pending notification or terminally archived. This keeps
+   * authorized retries (including pending-notification retries) available even
+   * when the template has been unregistered, while unrelated callers receive a
+   * stable `ActionNotAllowedError` without attempt IDs or notification state.
+   */
+  authorizeArchivedOutcome(message, user) {
+    if (!message.isSender(user) && !message.isReceiver(user)) {
+      throw new ActionNotAllowedError();
+    }
+  }
+  /** Call only with an authoritative, unpopulated archive read. */
+  throwArchivedOutcome(message, user) {
+    this.authorizeArchivedOutcome(message, user);
+    if (message.actionNotificationState === "pending" || message.actionNotificationState === "failed") {
+      throw new ActionNotificationPendingError(String(message._id), message.actionAttemptId ?? "", void 0);
+    }
+    throw new MessageArchivedError(String(message._id));
+  }
+  /**
+   * Authoritative post-claim authorization bound to the persisted document
+   * returned by the atomic claim. Re-validates the requested template/action
+   * selection and the sender/receiver, permission, and condition checks
+   * against persisted `templateCd`, parties, roles, and payload data.
+   *
+   * Supported update protocol: the guarantee covers the document state as of
+   * the atomic claim (`findOneAndUpdate` returning the persisted document).
+   * Host writes that commit before the claim are observed; host writes that
+   * commit after the claim (during handler execution) are not prevented. Hosts
+   * must not mutate action-relevant fields (`templateCd`, `toUser`/`toRoles`/
+   * `fromUser`, condition payload) concurrently with in-flight actions outside
+   * a coordinated protocol. A fresh-document read alone is not a substitute
+   * for this claim-bound check.
+   */
+  authorizeClaimedAction(templateCd, actionCd, claimed, user, options = {}) {
+    if (templateCd !== claimed.templateCd) {
+      throw new ActionTemplateMismatchError(claimed.templateCd, templateCd);
     }
-    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);
+    const template = this.registry.find(claimed.templateCd);
+    if (!template) throw new TemplateNotFoundError(claimed.templateCd);
+    const action = template.actions.find((a) => a.actionCd === actionCd);
+    if (!action) throw new ActionNotFoundError(claimed.templateCd, actionCd);
+    if (!isActionAllowed(action, user, claimed, { permissions: options.permissions })) {
+      throw new ActionNotAllowedError();
+    }
+    return action;
+  }
+  async releaseDeniedActionClaim(claim, error) {
+    const { message, actionAttemptId, actionOwnerToken } = claim;
+    if (!claim.fresh) {
+      await this.markActionRetryable(message._id, actionAttemptId, actionOwnerToken, error, message);
+      return;
+    }
+    const Message = this.resolveModel("active", message);
+    const updated = await Message.updateOne(
+      { _id: message._id, actionState: "processing", actionAttemptId, actionOwnerToken },
+      {
+        $set: {
+          actionState: "active",
+          actionCd: null,
+          actionAttemptId: null,
+          actionOwnerToken: null,
+          actionClaimedBy: null,
+          actionClaimedAt: null,
+          actionLeaseExpiresAt: null,
+          actionFailureMessage: null
+        }
       }
-      throw new MessageArchivedError(String(messageId));
+    );
+    if ((updated.matchedCount ?? updated.n ?? 0) !== 1) {
+      throw new ActionConflictError(String(message._id));
     }
-    throw new ActionConflictError(String(messageId));
   }
-  async markActionRetryable(messageId, actionAttemptId, error, sourceDocument) {
+  async markActionRetryable(messageId, actionAttemptId, actionOwnerToken, error, sourceDocument) {
     const Message = this.resolveModel("active", sourceDocument);
-    await Message.updateOne(
-      { _id: messageId, actionState: "processing", actionAttemptId },
+    const updated = await Message.updateOne(
+      { _id: messageId, actionState: "processing", actionAttemptId, actionOwnerToken },
       {
         $set: {
           actionState: "retryable",
@@ -1302,8 +1446,11 @@ var MessageService = class {
         }
       }
     );
+    if ((updated.matchedCount ?? updated.n ?? 0) !== 1) {
+      throw new ActionConflictError(String(messageId));
+    }
   }
-  async archiveClaimedMessage(message, action, user, actionAttemptId) {
+  async archiveClaimedMessage(message, action, user, actionAttemptId, actionOwnerToken) {
     const Message = this.resolveModel("active", message);
     const MessageArchive = this.resolveModel("archive", message, Message);
     const messageId = message._id;
@@ -1314,55 +1461,63 @@ var MessageService = class {
     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
-      );
+    delete data.actionOwnerToken;
+    const ownershipFilter = {
+      _id: messageId,
+      actionState: "processing",
+      actionAttemptId,
+      actionOwnerToken
+    };
+    const ownership = await Message.findOne(ownershipFilter);
+    if (!ownership) {
+      throw new ActionConflictError(String(messageId));
+    }
+    const operation = async (session) => {
+      try {
+        await MessageArchive.create(
+          [
+            {
+              ...data,
+              actionCd: action.actionCd,
+              archivedBy: user._id,
+              archivedAt: /* @__PURE__ */ new Date(),
+              actionAttemptId,
+              actionOwnerToken,
+              actionNotificationState: notificationState,
+              actionNotificationError: null,
+              actionNotificationAttemptedAt: null
+            }
+          ],
+          { session, ordered: true }
+        );
+      } catch (error) {
+        if (isDuplicateKeyError(error)) {
+          throw new ActionConflictError(String(messageId));
+        }
+        throw error;
+      }
       const deleted = await Message.deleteOne(
-        { _id: messageId, actionState: "processing", actionAttemptId },
-        session2 ? { session: session2 } : void 0
+        { _id: messageId, actionState: "processing", actionAttemptId, actionOwnerToken },
+        { session }
       );
       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);
+      await runMessageTransaction(Message, operation, {
+        operation: "actionArchive",
+        onTransactionCleanupFailure: this.onTransactionCleanupFailure
       });
     } catch (error) {
-      if (this.isTransactionSupportError(error)) {
-        await this.markActionRetryable(messageId, actionAttemptId, error, message);
-        throw new MessageTransactionRequiredError(error);
-      }
-      await this.markActionRetryable(messageId, actionAttemptId, error, message);
+      await this.markActionRetryable(messageId, actionAttemptId, actionOwnerToken, error, message);
       throw error;
-    } finally {
-      await session.endSession();
     }
   }
-  async markActionNotificationState(messageId, actionAttemptId, state, error, sourceDocument) {
+  async markActionNotificationState(messageId, actionAttemptId, actionOwnerToken, state, error, sourceDocument) {
     const MessageArchive = this.resolveModel("archive", sourceDocument);
-    await MessageArchive.updateOne(
-      { _id: messageId, actionAttemptId },
+    const updated = await MessageArchive.updateOne(
+      { _id: messageId, actionAttemptId, actionOwnerToken },
       {
         $set: {
           actionNotificationState: state,
@@ -1371,22 +1526,25 @@ var MessageService = class {
         }
       }
     );
+    if ((updated.matchedCount ?? updated.n ?? 0) !== 1) {
+      throw new ActionConflictError(String(messageId));
+    }
   }
   async runSenderNotification(action, ctx, message) {
     if (!action.senderNotification) return;
-    let content;
+    let content2;
     if (typeof action.senderNotification === "function") {
-      content = await action.senderNotification(ctx);
+      content2 = await action.senderNotification(ctx);
     } else {
-      content = action.senderNotification;
+      content2 = action.senderNotification;
     }
     const senderTitle = message.senderContent?.title ?? "";
-    const senderNotificationContent = isString(content) ? { title: senderTitle, long: content, short: content } : {
-      title: content.title || senderTitle,
-      long: content.long,
-      short: content.short || content.long
+    const senderNotificationContent = isString(content2) ? { title: senderTitle, long: content2, short: content2 } : {
+      title: content2.title || senderTitle,
+      long: content2.long,
+      short: content2.short || content2.long
     };
-    const documents = !isString(content) ? content.documents || [] : [];
+    const documents = !isString(content2) ? content2.documents || [] : [];
     if (message.fromUser) {
       await this.createNotification(
         {
@@ -1425,6 +1583,19 @@ var MessageService = class {
     }
     return value;
   }
+  validateDurationOption(name, value, min) {
+    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value)) {
+      throw new InvalidMessageServiceOptionError(
+        `${name} must be a finite safe integer in [${min}, ${MAX_MESSAGE_SERVICE_TIMEOUT_MS}] ms`
+      );
+    }
+    if (value < min || value > MAX_MESSAGE_SERVICE_TIMEOUT_MS) {
+      throw new InvalidMessageServiceOptionError(
+        `${name} must be a finite safe integer in [${min}, ${MAX_MESSAGE_SERVICE_TIMEOUT_MS}] ms`
+      );
+    }
+    return value;
+  }
   normalizeListLimit(value) {
     if (value === void 0) {
       return this.defaultListLimit;
@@ -1451,41 +1622,53 @@ var MessageService = class {
     };
   }
   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();
-      }
-      return id;
-    }
-    if (user._id instanceof mongoose5.Types.ObjectId) {
-      return String(user._id);
-    }
-    throw new InvalidMessageUserError();
+    return requireMessageUserId(user);
   }
   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");
+  async findArchivedByClientRequestScope(scope) {
+    const MessageArchive = this.resolveModel("archive");
+    const docs = await MessageArchive.find(scope).sort({ clientRequestItemIndex: 1, _id: 1 }).limit(Number.MAX_SAFE_INTEGER);
+    return docs;
+  }
+  /**
+   * Merge one active snapshot and one archive snapshot for a completed scope.
+   *
+   * Archival moves a document with create-then-delete ordering, so with an
+   * active-then-archive read order a moving item is always visible in at least
+   * one snapshot (no miss). A commit landing between the two reads surfaces
+   * the same `_id` in both snapshots; deduplicating by `_id` string keeps the
+   * active copy and prevents double-counting. Returns the merged batch sorted
+   * by exact `clientRequestItemIndex`, or `null` when the merged set does not
+   * satisfy the exact distinct-index contract.
+   */
+  mergeReplayBatch(active, archived, itemCount) {
+    const byId = /* @__PURE__ */ new Map();
+    for (const doc of [...active, ...archived]) {
+      const key = String(doc._id);
+      if (!byId.has(key)) {
+        byId.set(key, doc);
       }
-      return null;
-    }
-    if (reservation.state === "failed") {
-      throw new ClientRequestFailedError(scope.clientRequestId, reservation.failureMessage);
     }
-    if (reservation.state !== "completed") {
+    const docs = [...byId.values()];
+    const indexes = new Set(docs.map((doc) => doc.clientRequestItemIndex));
+    const hasExpectedIndexes = docs.length === itemCount && indexes.size === itemCount && Array.from({ length: itemCount }, (_, index) => indexes.has(index)).every(Boolean);
+    if (!hasExpectedIndexes) {
       return null;
     }
+    return docs.sort((a, b) => {
+      const indexA = a.clientRequestItemIndex ?? 0;
+      const indexB = b.clientRequestItemIndex ?? 0;
+      if (indexA !== indexB) return indexA - indexB;
+      return String(a._id).localeCompare(
+        String(b._id)
+      );
+    });
+  }
+  async buildCompletedReplay(reservation, scope, cachedActive, cachedArchived) {
     if (reservation.itemCount === null || reservation.itemCount < 0 || !Number.isInteger(reservation.itemCount)) {
       throw new ClientRequestInconsistentStateError(
         scope.clientRequestId,
@@ -1493,7 +1676,9 @@ var MessageService = class {
       );
     }
     if (reservation.itemCount === 0) {
-      if (docs.length > 0) {
+      const active2 = cachedActive ?? await this.findByClientRequestScope(scope);
+      const archived2 = cachedArchived ?? await this.findArchivedByClientRequestScope(scope);
+      if (active2.length > 0 || archived2.length > 0) {
         throw new ClientRequestInconsistentStateError(
           scope.clientRequestId,
           "completed zero-item reservation has messages"
@@ -1501,20 +1686,55 @@ var MessageService = class {
       }
       return [];
     }
-    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)
-        )}`
-      );
+    const itemCount = reservation.itemCount;
+    let active = cachedActive ?? await this.findByClientRequestScope(scope);
+    let archived = cachedArchived ?? await this.findArchivedByClientRequestScope(scope);
+    const merged = this.mergeReplayBatch(active, archived, itemCount);
+    if (merged) {
+      return merged;
+    }
+    active = await this.findByClientRequestScope(scope);
+    archived = await this.findArchivedByClientRequestScope(scope);
+    const reconciled = this.mergeReplayBatch(active, archived, itemCount);
+    if (reconciled) {
+      return reconciled;
+    }
+    const indexes = new Set([...active, ...archived].map((doc) => doc.clientRequestItemIndex));
+    throw new ClientRequestInconsistentStateError(
+      scope.clientRequestId,
+      `completed reservation expects item indexes 0..${itemCount - 1} but found ${JSON.stringify(Array.from(indexes))}`
+    );
+  }
+  async findCompletedClientRequestReplay(scope) {
+    const reservation = await this.findClientRequestReservation(scope);
+    if (!reservation) {
+      const active = await this.findByClientRequestScope(scope);
+      const archived = await this.findArchivedByClientRequestScope(scope);
+      if (active.length === 0 && archived.length === 0) {
+        return null;
+      }
+      const reread = await this.findClientRequestReservation(scope);
+      if (!reread) {
+        throw new ClientRequestInconsistentStateError(scope.clientRequestId, "messages exist without a reservation");
+      }
+      if (reread.state === "failed") {
+        throw new ClientRequestFailedError(scope.clientRequestId, reread.failureMessage);
+      }
+      if (reread.state !== "completed") {
+        return null;
+      }
+      return this.buildCompletedReplay(reread, scope, active, archived);
     }
-    return docs;
+    if (reservation.state === "failed") {
+      throw new ClientRequestFailedError(scope.clientRequestId, reservation.failureMessage);
+    }
+    if (reservation.state !== "completed") {
+      return null;
+    }
+    return this.buildCompletedReplay(reservation, scope);
   }
   async acquireClientRequestStart(scope) {
-    const deadline = Date.now() + this.clientRequestWaitMs;
+    const deadline = this.clientRequestNow() + this.clientRequestWaitMs;
     while (true) {
       const lease = await this.tryAcquireClientRequestLease(scope);
       if (lease) {
@@ -1524,101 +1744,509 @@ var MessageService = class {
       if (replay !== null) {
         return { kind: "replay", replay };
       }
-      if (Date.now() >= deadline) {
+      if (this.clientRequestNow() >= deadline) {
         throw new ClientRequestPendingError(scope.clientRequestId);
       }
-      await this.clientRequestDelay(Math.min(this.clientRequestPollMs, Math.max(deadline - Date.now(), 0)));
+      await this.clientRequestDelay(
+        Math.min(this.clientRequestPollMs, Math.max(deadline - this.clientRequestNow(), 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({
+        ...scope,
+        state: "pending",
+        itemCount: null,
+        leaseOwnerId: ownerId,
+        leaseExpiresAt: new Date(this.clientRequestNow() + this.clientRequestLeaseMs)
+      });
+      return { ownerId };
+    } catch (error) {
+      if (isDuplicateKeyError(error)) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async tryTakeOverStaleClientRequestReservation(scope) {
+    const MessageRequest = this.resolveModel("request");
+    const ownerId = randomUUID();
+    const reservation = await MessageRequest.findOneAndUpdate(
+      { ...scope, state: "pending", leaseExpiresAt: { $lte: new Date(this.clientRequestNow()) } },
+      {
+        $set: {
+          leaseOwnerId: ownerId,
+          leaseExpiresAt: new Date(this.clientRequestNow() + this.clientRequestLeaseMs)
+        }
+      },
+      { returnDocument: "after" }
+    );
+    return reservation ? { ownerId } : null;
+  }
+  async findClientRequestReservation(scope) {
+    const MessageRequest = this.resolveModel("request");
+    return await MessageRequest.findOne(scope);
+  }
+  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
+        }
+      }
+    );
+  }
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  isArchivedMessage(message) {
+    return "archivedAt" in message;
+  }
+  applyPopulate(query, populate) {
+    if (!populate) {
+      return query;
+    }
+    const items = Array.isArray(populate) ? populate : [populate];
+    let current = query;
+    for (const item of items) {
+      current = current.populate(item);
+    }
+    return current;
+  }
+  async findByIdWithOptions(model, id, options) {
+    const baseQuery = model.findById(id);
+    const selectedQuery = options.select === void 0 ? baseQuery : baseQuery.select(options.select);
+    const query = this.applyPopulate(selectedQuery, options.populate);
+    return query;
+  }
+};
+
+// 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 async function archive(actionCd, archivedBy, registry) {
+    if (typeof actionCd !== "string" || actionCd.length === 0) {
+      throw new ActionNotFoundError(
+        String(this.templateCd ?? ""),
+        String(actionCd)
+      );
+    }
+    if (!isValidMessageUserId(archivedBy)) {
+      throw new InvalidMessageUserError();
+    }
+    if (!registry || typeof registry.find !== "function") {
+      throw new TemplateNotFoundError(String(this.templateCd ?? ""));
+    }
+    const templateCd = this.templateCd;
+    const template = registry.find(templateCd);
+    if (!template) {
+      throw new TemplateNotFoundError(templateCd);
+    }
+    if (!includesAction(templateCd, actionCd, registry)) {
+      throw new ActionNotFoundError(templateCd, actionCd);
+    }
+    const activeModel = this.constructor;
+    const connection = activeModel.db;
+    if (!connection || typeof connection.startSession !== "function") {
+      throw new MessageTransactionRequiredError(
+        new Error("message-service: direct archive() requires a Mongoose connection with session/transaction support")
+      );
+    }
+    const MessageArchive = resolveDocumentModel(this, ctx.archiveModelName, "archive");
+    const ActiveTyped = activeModel;
+    const messageId = this._id;
+    const existingSession = typeof this.$session === "function" ? this.$session() : null;
+    const run = async (session) => {
+      const now = /* @__PURE__ */ new Date();
+      const fresh = await ActiveTyped.findOne({ _id: messageId }).session(session).lean();
+      if (!fresh) {
+        const archivedMatch = await MessageArchive.findOne({ _id: messageId }).session(session).select("_id").lean().catch(() => null);
+        if (archivedMatch) {
+          throw new MessageArchivedError(String(messageId));
+        }
+        throw new MessageNotFoundError(String(messageId));
+      }
+      const state = fresh.actionState;
+      const leaseExpiresAt = fresh.actionLeaseExpiresAt;
+      const liveLease = state === "processing" && leaseExpiresAt instanceof Date && leaseExpiresAt.getTime() > now.getTime();
+      if (state === "processing" && !liveLease) {
+        const expired = leaseExpiresAt instanceof Date && leaseExpiresAt.getTime() <= now.getTime();
+        if (!expired) {
+          throw new ActionConflictError(String(messageId));
+        }
+      } else if (liveLease) {
+        throw new ActionConflictError(String(messageId));
+      }
+      const source = { ...fresh };
+      delete source.actionState;
+      delete source.actionClaimedBy;
+      delete source.actionClaimedAt;
+      delete source.actionLeaseExpiresAt;
+      delete source.actionFailureMessage;
+      const archiveDoc = {
+        ...source,
+        actionCd,
+        archivedBy,
+        archivedAt: /* @__PURE__ */ new Date(),
+        actionNotificationState: "none",
+        actionNotificationError: null,
+        actionNotificationAttemptedAt: null
+      };
+      try {
+        await MessageArchive.create([archiveDoc], { session, ordered: true });
+      } catch (error) {
+        if (isDuplicateKeyError(error)) {
+          throw new MessageArchivedError(String(messageId));
+        }
+        throw error;
+      }
+      const deleted = await ActiveTyped.deleteOne(
+        {
+          _id: messageId,
+          $or: [
+            { actionState: "active" },
+            { actionState: "retryable" },
+            { actionState: "processing", actionLeaseExpiresAt: { $lte: now } },
+            { actionState: null },
+            { actionState: { $exists: false } }
+          ]
+        },
+        { session }
+      );
+      if ((deleted.deletedCount ?? deleted.n ?? 0) !== 1) {
+        throw new ActionConflictError(String(messageId));
+      }
+    };
+    try {
+      await runMessageTransaction(activeModel, run, {
+        operation: "directArchive",
+        session: existingSession ?? void 0,
+        onTransactionCleanupFailure: ctx.onTransactionCleanupFailure
+      });
+    } catch (error) {
+      if (isDuplicateKeyError(error)) {
+        throw new MessageArchivedError(String(messageId));
+      }
+      throw error;
+    }
+  };
+}
+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 (!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;
     }
-  }
-  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();
+    if (!user?.email) {
+      return;
+    }
+    const long = this.receiverContent.long || "";
+    const short = this.receiverContent.short || "";
+    const body = long.length > short.length ? long : short;
     try {
-      await MessageRequest.create({
-        ...scope,
-        state: "pending",
-        itemCount: null,
-        leaseOwnerId: ownerId,
-        leaseExpiresAt: new Date(Date.now() + this.clientRequestLeaseMs)
-      });
-      return { ownerId };
+      await ctx.emailNotifier(user.email, title, body);
     } catch (error) {
-      if (this.isDuplicateKeyError(error)) {
-        return null;
-      }
-      throw error;
+      await reportEmailFailure(ctx, "notifier", error, this, title);
     }
+  };
+}
+async function reportEmailFailure(ctx, stage, error, message, title) {
+  try {
+    await ctx.onEmailDeliveryFailure?.({
+      stage,
+      error,
+      messageId: message._id,
+      recipientId: message.toUser,
+      title
+    });
+  } catch {
   }
-  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" }
+}
+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 on Mongoose connection "${connectionName}". Register the model on that connection before buildMessageSchema().`
     );
-    return reservation ? { ownerId } : null;
   }
-  async findClientRequestReservation(scope) {
-    const MessageRequest = this.resolveModel("request");
-    return await MessageRequest.findOne(scope);
+}
+function resolveConfig(config) {
+  return {
+    onTransactionCleanupFailure: config?.onTransactionCleanupFailure,
+    emailNotifier: config?.emailNotifier ?? null,
+    onEmailDeliveryFailure: config?.onEmailDeliveryFailure,
+    emailNotificationExclusions: (config?.emailNotificationExclusions ?? []).map(normalizeEmailTitle),
+    userModelName: config?.userModelName ?? "User",
+    archiveModelName: config?.archiveModelName ?? MESSAGE_ARCHIVE_MODEL_NAME,
+    connection: config?.connection ?? mongoose3
+  };
+}
+function buildMessageSchema(config) {
+  const resolved = resolveConfig(config);
+  if (resolved.emailNotifier) {
+    assertModelRegistered(resolved.connection, resolved.userModelName, "user");
   }
-  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
-        }
+  const schema = new mongoose3.Schema(BaseMessageFields, {
+    timestamps: 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(
+    { 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" }
       }
+    }
+  );
+  schema.methods.isSender = isSender;
+  schema.methods.isReceiver = isReceiver;
+  schema.methods.archive = createArchiveMethod({
+    archiveModelName: resolved.archiveModelName,
+    onTransactionCleanupFailure: resolved.onTransactionCleanupFailure
+  });
+  if (resolved.emailNotifier) {
+    schema.pre("save", createEmailStateCaptureHook());
+    schema.post(
+      "save",
+      createPostSaveEmailHook({
+        emailNotifier: resolved.emailNotifier,
+        onEmailDeliveryFailure: resolved.onEmailDeliveryFailure,
+        emailNotificationExclusions: resolved.emailNotificationExclusions,
+        userModelName: resolved.userModelName
+      })
     );
   }
-  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));
-  }
-  isArchivedMessage(message) {
-    return "archivedAt" in message;
-  }
-  applyPopulate(query, populate) {
-    if (!populate) {
-      return query;
+  return schema;
+}
+var MessageSchema = buildMessageSchema();
+
+// src/schemas/message-archive.ts
+import mongoose4 from "mongoose";
+function buildMessageArchiveSchema() {
+  const schema = new mongoose4.Schema(
+    {
+      ...BaseMessageFields,
+      actionCd: { type: String, default: "" },
+      archivedBy: { type: mongoose4.Schema.Types.ObjectId, default: null, index: true },
+      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
     }
-    const items = Array.isArray(populate) ? populate : [populate];
-    let current = query;
-    for (const item of items) {
-      current = current.populate(item);
+  );
+  schema.index({ createdAt: 1 });
+  schema.index(
+    { clientRequestOwnerId: 1, templateCd: 1, clientRequestId: 1, createdAt: 1, _id: 1 },
+    {
+      partialFilterExpression: {
+        clientRequestId: { $type: "string" },
+        clientRequestOwnerId: { $type: "string" },
+        templateCd: { $type: "string" }
+      }
     }
-    return current;
+  );
+  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" }
+      }
+    }
+  );
+  schema.methods.isSender = isSender;
+  schema.methods.isReceiver = isReceiver;
+  return schema;
+}
+var MessageArchiveSchema = buildMessageArchiveSchema();
+
+// src/schemas/message-request.ts
+import mongoose5 from "mongoose";
+function buildMessageRequestSchema() {
+  const schema = new mongoose5.Schema(
+    {
+      clientRequestId: { type: String, required: true },
+      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({ clientRequestOwnerId: 1, templateCd: 1, clientRequestId: 1 }, { unique: true });
+  schema.index({ updatedAt: 1 });
+  schema.index({ state: 1, leaseExpiresAt: 1 });
+  return schema;
+}
+var MessageRequestSchema = buildMessageRequestSchema();
+
+// src/providers/email.ts
+var NoopEmailProvider = class {
+  async sendNotification(_to, _title, _body) {
   }
-  async findByIdWithOptions(model, id, options) {
-    const baseQuery = model.findById(id);
-    const selectedQuery = options.select === void 0 ? baseQuery : baseQuery.select(options.select);
-    const query = this.applyPopulate(selectedQuery, options.populate);
-    return query;
+};
+
+// src/providers/payment.ts
+var NoopPaymentProvider = class {
+  async createSession(_user, _code, _priceArgs) {
+    return null;
+  }
+  async expireSession(_sessionId) {
+  }
+  async refundPayment(_sessionId) {
   }
 };
 
+// src/public-message.ts
+import { Types as Types2 } from "mongoose";
+function referenceId(value) {
+  if (typeof value === "string" && value.length > 0) return value;
+  if (value instanceof Types2.ObjectId) return value.toHexString();
+  return null;
+}
+function populatedId(value) {
+  return referenceId(value) ?? (value && typeof value === "object" && "_id" in value ? referenceId(value._id) : null);
+}
+function party(value) {
+  const id = referenceId(value);
+  if (id !== null) return id;
+  if (!value || typeof value !== "object" || !("_id" in value)) return null;
+  const populated = referenceId(value._id);
+  if (populated === null) return null;
+  const result = { _id: populated };
+  if ("displayName" in value && typeof value.displayName === "string") result.displayName = value.displayName;
+  if ("email" in value && typeof value.email === "string") result.email = value.email;
+  return result;
+}
+function content(value) {
+  return { title: value.title, long: value.long, short: value.short };
+}
+function serializePublicMessage(message) {
+  const id = referenceId(message._id);
+  if (id === null) throw new TypeError("Message must have a string or ObjectId _id");
+  const result = {
+    _id: id,
+    templateCd: message.templateCd,
+    type: message.type,
+    fromUser: party(message.fromUser),
+    toUser: party(message.toUser),
+    toRoles: [...message.toRoles],
+    senderContent: content(message.senderContent),
+    receiverContent: content(message.receiverContent),
+    documents: message.documents.map(populatedId).filter((value) => value !== null),
+    paymentSession: message.paymentSession,
+    paymentCd: message.paymentCd,
+    payload: message.payload,
+    display: message.display,
+    actionState: message.actionState,
+    actionCd: message.actionCd,
+    actionAttemptId: message.actionAttemptId,
+    createdAt: message.createdAt.toISOString(),
+    updatedAt: message.updatedAt.toISOString()
+  };
+  if (message.archivedAt != null) {
+    result.archivedAt = message.archivedAt.toISOString();
+    result.archivedBy = populatedId(message.archivedBy);
+    result.actionNotificationState = message.actionNotificationState ?? "none";
+  }
+  return result;
+}
+
 // src/route-factory.ts
 import JsonRouter from "@web-ts-toolkit/express-json-router";
 var ACTION_CD_PATTERN = /^[a-zA-Z0-9_-]+$/;
@@ -1678,7 +2306,9 @@ function assertValidBody(body) {
   }
 }
 function requireUser(user) {
-  if (!user || user._id === void 0 || user._id === null || String(user._id).trim().length === 0) {
+  try {
+    requireMessageUserId(user);
+  } catch {
     throw new JsonRouter.clientErrors.UnauthorizedError("authentication required");
   }
   return user;
@@ -1714,28 +2344,75 @@ function mapServiceError(error) {
   if (error instanceof InvalidMessageUserError) {
     throw new JsonRouter.clientErrors.UnauthorizedError("authentication required");
   }
-  if (error instanceof ClientRequestPendingError || error instanceof ClientRequestFailedError) {
+  if (error instanceof ClientRequestPendingError) {
     throw new JsonRouter.clientErrors.ConflictError(error.message);
   }
+  if (error instanceof ClientRequestFailedError) {
+    throw new JsonRouter.clientErrors.ConflictError(
+      `clientRequestId "${error.clientRequestId}" previously failed; retry with a new clientRequestId`
+    );
+  }
   if (isMongooseCastError(error)) {
     throw new JsonRouter.clientErrors.BadRequestError("id must be a valid ObjectId");
   }
   throw error;
 }
+var SERVICE_CONSTRUCTION_KEYS = [
+  "getModel",
+  "connection",
+  "modelNames",
+  "paymentProvider",
+  "onPaymentCompensationFailure",
+  "onTransactionCleanupFailure",
+  "adminRoles",
+  "registry",
+  "defaultListLimit",
+  "maxListLimit",
+  "clientRequestLeaseMs",
+  "clientRequestWaitMs",
+  "clientRequestPollMs",
+  "clientRequestDelay",
+  "clientRequestNow"
+];
 function createMessageRoutes(options) {
   const {
-    getModel,
-    paymentProvider = null,
-    onPaymentCompensationFailure,
-    adminRoles,
-    registry,
     authMiddleware = [],
     getUser = defaultGetUser,
     getPermissions = defaultGetPermissions,
     getIdentity = defaultGetIdentity,
     adminPermissionKey = "is.admin"
   } = options;
-  const service = new MessageService({ getModel, paymentProvider, onPaymentCompensationFailure, adminRoles, registry });
+  let service;
+  if (options.service !== void 0) {
+    const conflicts = SERVICE_CONSTRUCTION_KEYS.filter(
+      (key) => options[key] !== void 0
+    );
+    if (conflicts.length > 0) {
+      throw new InvalidMessageServiceOptionError(
+        `createMessageRoutes: "service" cannot be combined with service construction options: ${conflicts.join(", ")}. Pass route-only options (authMiddleware, getUser, getPermissions, getIdentity, adminPermissionKey) alongside "service", or construct without "service".`
+      );
+    }
+    service = options.service;
+  } else {
+    const construction = options;
+    service = new MessageService({
+      getModel: construction.getModel,
+      connection: construction.connection,
+      modelNames: construction.modelNames,
+      paymentProvider: construction.paymentProvider,
+      onPaymentCompensationFailure: construction.onPaymentCompensationFailure,
+      onTransactionCleanupFailure: construction.onTransactionCleanupFailure,
+      adminRoles: construction.adminRoles,
+      registry: construction.registry,
+      defaultListLimit: construction.defaultListLimit,
+      maxListLimit: construction.maxListLimit,
+      clientRequestLeaseMs: construction.clientRequestLeaseMs,
+      clientRequestWaitMs: construction.clientRequestWaitMs,
+      clientRequestPollMs: construction.clientRequestPollMs,
+      clientRequestDelay: construction.clientRequestDelay,
+      clientRequestNow: construction.clientRequestNow
+    });
+  }
   const router = new JsonRouter("", authMiddleware);
   router.post("/new/:templateCd", async (req) => {
     const templateCd = req.params.templateCd;
@@ -1750,7 +2427,7 @@ function createMessageRoutes(options) {
     const hasClientRequestId = Object.prototype.hasOwnProperty.call(body, "clientRequestId");
     assertValidClientRequestId(hasClientRequestId ? clientRequestId : void 0);
     try {
-      return await service.createMessage({
+      const messages = await service.createMessage({
         templateCd,
         user,
         roles,
@@ -1761,6 +2438,7 @@ function createMessageRoutes(options) {
         req,
         clientRequestId: hasClientRequestId ? clientRequestId : void 0
       });
+      return messages.map(serializePublicMessage);
     } catch (error) {
       mapServiceError(error);
     }
@@ -1772,7 +2450,7 @@ function createMessageRoutes(options) {
     assertValidMessageId(id);
     assertValidUsertype(usertype);
     const permissions = getPermissions(req);
-    const isAdmin = !!permissions[adminPermissionKey];
+    const isAdmin = hasExplicitPermissionGrant(permissions, adminPermissionKey);
     let result;
     try {
       result = await service.getActions(id, usertype, { permissions, user, isAdmin });
@@ -1832,8 +2510,10 @@ export {
   ClientRequestPendingError,
   GENERIC_NOTIFICATION_TEMPLATE_CD,
   InvalidClientRequestIdError,
+  InvalidMessageServiceOptionError,
   InvalidMessageUserError,
   InvalidPaginationValueError,
+  MAX_MESSAGE_SERVICE_TIMEOUT_MS,
   MESSAGE_ARCHIVE_MODEL_NAME,
   MESSAGE_MODEL_NAME,
   MESSAGE_REQUEST_MODEL_NAME,
@@ -1848,6 +2528,7 @@ export {
   MessageTransactionRequiredError,
   NoopEmailProvider,
   NoopPaymentProvider,
+  PaymentSessionCompensationAggregateError,
   PaymentSessionCompensationError,
   TemplateNotFoundError,
   TemplateRegistry,
@@ -1858,7 +2539,13 @@ export {
   createMessageRoutes,
   defaultRegistry,
   filterActions,
+  hasExplicitPermissionGrant,
   includesAction,
+  interpolateMessageContent,
   interpolateTemplate,
-  isActionAllowed
+  isActionAllowed,
+  isValidMessageUserId,
+  requireMessageUserId,
+  resolveUiTemplate,
+  serializePublicMessage
 };