@web-ts-toolkit/message-service 0.52.0 → 0.53.0

package/index.d.mts

@@ -38,13 +38,30 @@ interface PrepareResult {
     fromUser?: UserId;
     toUser?: UserId;
     toRoles?: string[];
+    /**
+     * Per-item attachment ObjectIds; `[]` intentionally clears attachments.
+     * Omitted/undefined uses the original `PrepareContext.payload.documents`
+     * (or `[]` when absent), not this result's `payload.documents`.
+     * The selected array is copied per item without mutating either input.
+     */
+    documents?: mongoose.Types.ObjectId[];
     payload?: Record<string, unknown>;
     display?: Record<string, unknown>;
+    /**
+     * Nonempty code overrides the template and requires a payment session even
+     * without recipients. `''`/omission inherits `MessageTemplate.paymentCd`;
+     * codes are not trimmed. Absent/null providers throw `PaymentProviderRequiredError`.
+     */
     paymentCd?: string;
     priceArgs?: Record<string, unknown>;
 }
 interface ActionContext {
     message: IMessage | IMessageArchive;
+    /**
+     * Validated snapshot of `_id`, `id`, `roles`, and `displayName`, including
+     * getter-backed values. `_id` is the normalized string identity; roles are
+     * copied. Extra authentication-document fields are excluded; `req` is original.
+     */
     user: MessageUser;
     /**
      * Stable, persisted idempotency key for this action attempt. Handlers that
@@ -53,6 +70,14 @@ interface ActionContext {
      * exactly-once.
      */
     actionAttemptId?: string;
+    /**
+     * Submitted command, or the current action's synchronous `parseInput` output.
+     * HTTP supplies `req.body`; direct calls supply `data.input` explicitly (never
+     * inferred from `req`). Separate from action metadata and `message.payload`.
+     * Unvalidated/pass-through when no parser is configured. Hosts own durable
+     * command/result binding and deduplication by `actionAttemptId`.
+     */
+    input?: unknown;
     getModel: (name: string) => mongoose.Model<unknown>;
     expireSession?: (sessionId: string) => Promise<void>;
     refundPayment?: (sessionId: string) => Promise<void>;
@@ -81,7 +106,22 @@ interface MessageAction {
     permission?: string;
     condition?: (message: IMessage) => boolean;
     confirmation?: ActionConfirmation;
+    /** Presentation metadata, not submitted input or an enforced command schema. */
     payload?: Record<string, unknown>;
+    /**
+     * Optional synchronous, deterministic, effect-free command parser. Runs once
+     * per acquisition after authoritative claimed authorization, before the handler.
+     * Treat raw input as read-only; return a normalized allowlisted command for
+     * `ActionContext.input`, or throw `ActionInputValidationError` (HTTP 400).
+     * Async parsers/thenables are unsupported server errors (HTTP 500); unexpected
+     * failures retain their cause and are sanitized over HTTP. No parser runs for
+     * unauthorized callers, listings, or archived outcomes.
+     *
+     * Pre-handler failure releases a fresh claim to active; retries/takeovers retain
+     * their stable attempt/action as retryable. Release is owner-fenced. This hook
+     * must not reserve commands or perform business effects; do that in the handler.
+     */
+    parseInput?: (input: unknown) => unknown;
     senderNotification?: string | ((ctx: ActionContext) => Promise<string | SenderNotificationContent>);
     runHandler: (ctx: ActionContext) => Promise<unknown>;
 }
@@ -104,6 +144,12 @@ interface MessageTemplate {
         short: string;
     };
     uiTemplate: UiTemplate;
+    /**
+     * Default code for fresh prepared items: `item.paymentCd || template.paymentCd || ''`.
+     * A nonempty effective code requires a payment session regardless of recipients;
+     * absent/null providers throw `PaymentProviderRequiredError`. Empty item codes
+     * cannot clear this default. Completed replays never re-evaluate payment.
+     */
     paymentCd?: string;
     prepareMessage: (ctx: PrepareContext) => Promise<PrepareResult | PrepareResult[] | null>;
     actions: MessageAction[];
@@ -119,7 +165,7 @@ type RegisteredUiTemplate = string | Readonly<{
 /**
  * Readonly action view matching the registry freeze depth: the action object,
  * its `confirmation`, and its `payload` are each shallow-frozen. Function
- * fields (`condition`, `runHandler`, `senderNotification`) keep their original
+ * fields (`condition`, `parseInput`, `runHandler`, `senderNotification`) keep their original
  * identity and remain callable.
  */
 type RegisteredMessageAction = Readonly<Omit<MessageAction, 'confirmation' | 'payload'>> & {
@@ -254,24 +300,39 @@ interface IMessageContent {
  * still allowing arbitrary strings.
  */
 type MessageType = 'notification' | 'request' | 'reminder' | 'approval' | (string & {});
+/**
+ * Native ObjectId or case-sensitive opaque string. User-facing IDs are trimmed;
+ * template party storage and archive ownership trim strings without stringifying
+ * native ObjectIds. Bundled party/archivedBy paths default to ObjectId: arbitrary
+ * strings require the README's active AND archive String-schema overrides.
+ * Stored ObjectIds match 24-hex principals in either case; stored strings compare
+ * exactly after trimming (even hex-looking strings). Request scopes always retain
+ * the existing trimmed, case-sensitive string keys; ObjectIds use lowercase hex.
+ */
 type UserId = mongoose.Types.ObjectId | string;
 type ActionLifecycleState = 'active' | 'processing' | 'retryable';
 type ActionNotificationState = 'none' | 'pending' | 'sent' | 'failed';
 /**
  * Minimal user shape accepted by MessageService methods.
+ * Plain objects, prototype getters, and hydrated Mongoose documents are
+ * supported. User-facing operations reject malformed `roles` with
+ * `InvalidMessageUserError`; omitted/undefined roles and `[]` are valid.
+ * Action handlers receive only these fields (with a copied roles array),
+ * not arbitrary authentication-document properties. The caller is not mutated.
  * `displayName` is optional but templates that interpolate `{{displayName}}`
  * will fall back to an empty string if it is absent.
  */
 interface MessageUser {
     _id: UserId;
     id?: string;
+    /** Exact, case-sensitive string roles; no coercion or substring matching. */
     roles?: string[];
     displayName?: string;
 }
 interface IMessageRelationshipMethods {
-    /** Match a string/ObjectId or populated party's `_id`; missing references never match. */
+    /** Stored ObjectIds accept either hex case; String parties match exact trimmed IDs, including populated `_id`s. Invalid roles/references never match. */
     isSender(user: MessageUser): boolean;
-    /** Match the recipient identity (including populated `_id`) or an explicit recipient role. */
+    /** Same stored-type ID policy as isSender, or an exact role; malformed user roles fail closed. */
     isReceiver(user: MessageUser): boolean;
 }
 interface IMessageMethods extends IMessageRelationshipMethods {
@@ -288,6 +349,8 @@ interface IMessageMethods extends IMessageRelationshipMethods {
      * `MessageArchivedError` (archive copy exists) or `MessageNotFoundError`.
      * Deployments without transaction support throw
      * `MessageTransactionRequiredError` before writing anything.
+     * String `archivedBy` is trimmed; native ObjectIds are preserved for schema
+     * casting. Opaque IDs require a String archive `archivedBy` path (see README).
      * Confirmed commit resolves even if session cleanup rejects; configure
      * `buildMessageSchema({ onTransactionCleanupFailure })` for diagnostics.
      * Observer failures cannot change the outcome. An attached `$session()` is
@@ -332,9 +395,11 @@ interface IBaseMessage {
 }
 type MongooseQueryHelpers = Record<string, unknown>;
 type IMessage = mongoose.Document<unknown, MongooseQueryHelpers, IMessageMethods> & IBaseMessage & IMessageMethods & {
+    _id: mongoose.Types.ObjectId;
     __v?: number;
 };
 type IMessageArchive = mongoose.Document<unknown, MongooseQueryHelpers, IMessageRelationshipMethods> & IBaseMessage & {
+    _id: mongoose.Types.ObjectId;
     actionCd: string;
     archivedBy: UserId;
     archivedAt: Date;
@@ -350,39 +415,7 @@ type IMessageArchive = mongoose.Document<unknown, MongooseQueryHelpers, IMessage
 declare const MESSAGE_MODEL_NAME = "Message";
 declare const MESSAGE_ARCHIVE_MODEL_NAME = "MessageArchive";
 declare const MESSAGE_REQUEST_MODEL_NAME = "MessageRequest";
-declare const MessageContentSchema: mongoose.Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
-    _id: false;
-}, {
-    title: string;
-    long: string;
-    short: string;
-}, mongoose.Document<unknown, {}, {
-    title: string;
-    long: string;
-    short: string;
-}, {
-    id: string;
-}, Omit<mongoose.DefaultSchemaOptions, "_id"> & {
-    _id: false;
-}> & Omit<{
-    title: string;
-    long: string;
-    short: string;
-} & {
-    _id: mongoose.Types.ObjectId;
-} & {
-    __v: number;
-}, "id"> & mongoose.HydratedDocumentOverrides<{
-    id: string;
-}>, unknown, {
-    title: string;
-    long: string;
-    short: string;
-} & {
-    _id: mongoose.Types.ObjectId;
-} & {
-    __v: number;
-}>;
+declare const MessageContentSchema: mongoose.Schema<IMessageContent>;
 /**
  * Base message fields shared between Message and MessageArchive.
  *
@@ -394,7 +427,40 @@ declare const MessageContentSchema: mongoose.Schema<any, mongoose.Model<any, any
  */
 declare const BaseMessageFields: Record<string, mongoose.SchemaTypeOptions<unknown>>;
 
+/**
+ * Best-effort delivery callback: receives the resolved address unchanged, the
+ * trimmed receiver title, and the longer receiver body (short wins ties).
+ * Throws/rejections report stage `notifier` without rejecting the saved message.
+ * Bind provider methods when they depend on `this`.
+ */
 type EmailNotifier = (email: string, title: string, message: string) => Promise<void> | void;
+/** Host context for address/preference lookup after a new, session-free message save. */
+interface EmailRecipientResolverContext {
+    /** Direct recipient ID after schema casting: ObjectId by default, or an opaque string with String party paths. */
+    readonly recipientId: UserId;
+    /** The hydrated document's owning connection, not the schema's eager-check connection or global Mongoose. */
+    readonly connection: mongoose.Connection;
+    /**
+     * Saved message fields, including templateCd, payload and display. A shallow
+     * read-only view of the hydrated document, not a cloned/frozen snapshot; do not
+     * mutate it or its nested values. No document methods are exposed by this type.
+     */
+    readonly message: Readonly<IBaseMessage> & {
+        readonly _id: mongoose.Types.ObjectId;
+    };
+}
+/**
+ * Resolve one recipient address, synchronously or asynchronously. Return null,
+ * undefined or an empty string to skip delivery without a failure event; no
+ * default lookup is attempted. Addresses are forwarded unchanged to the notifier;
+ * the host owns address validation, normalization and notification preferences.
+ * Throws/rejections report stage `recipientLookup` without rejecting the saved
+ * message. Awaited as part of the save hook; keep external lookups bounded.
+ * Not called for updates, session-bound saves, disabled email, missing direct
+ * recipients, or blank/excluded rendered titles. It does not enable role fan-out.
+ * Bind methods to their host instance when they depend on `this`.
+ */
+type EmailRecipientResolver = (context: EmailRecipientResolverContext) => string | null | undefined | Promise<string | null | undefined>;
 type EmailDeliveryFailureStage = 'recipientLookup' | 'notifier';
 interface EmailDeliveryFailureEvent {
     stage: EmailDeliveryFailureStage;
@@ -409,13 +475,24 @@ interface MessageSchemaConfig {
      * send a best-effort email notification to the recipient. Pass `null` (the
      * default) to disable.
      *
-     * When `null`, no save hooks are registered at all. When set, the schema
+     * When `null`, no email save hooks are registered. When set, the schema
      * registers a pre-save state capture plus a connection-local post-save
-     * hook: the post-save hook resolves user/archive models on the hydrated
-     * document's owning connection and skips session-bound writes (Mongoose
-     * save hooks run before the surrounding transaction commits).
+     * hook: recipient lookup uses the hydrated document's owning connection and
+     * skips session-bound writes (Mongoose save hooks run before the surrounding
+     * transaction commits). Bind provider methods to their instance when needed.
      */
     emailNotifier?: EmailNotifier | null;
+    /**
+     * Optional address/preference lookup for nested fields or external directories.
+     * Replaces the default connection-local `User.findById(toUser).select('email').lean()`
+     * adapter; no local user model or eager user-model check is needed when set.
+     * Called only with email enabled, for new session-free saves with a direct
+     * recipient and nonempty, nonexcluded rendered receiver title. Updates never
+     * resend. Return null/undefined/'' to skip without default fallback; failures use
+     * `onEmailDeliveryFailure`. Addresses are passed through unchanged. Bind host
+     * methods that depend on `this`; keep awaited external lookup work bounded.
+     */
+    emailRecipientResolver?: EmailRecipientResolver;
     /**
      * Called when recipient lookup or notifier delivery fails. The message save
      * has already succeeded and is not rolled back. If this hook throws, that
@@ -430,16 +507,16 @@ interface MessageSchemaConfig {
      */
     emailNotificationExclusions?: string[];
     /**
-     * Name of the Mongoose model that holds the recipient user records.
+     * Name of the Mongoose model used by the default recipient-address adapter.
      * Defaults to `'User'`. The post-save email hook resolves it on the
      * message document's owning connection
      * (`document.constructor.db.model(name)`) to look up the recipient's email
      * address, so connection-local apps must register the user model on the
      * same connection as the message models.
      *
-     * The model MUST be registered before the first save when `emailNotifier`
-     * is set — `buildMessageSchema` checks this eagerly to fail fast (pass
-     * `connection` when configuring connection-local schemas).
+     * The model MUST be registered before `buildMessageSchema()` when `emailNotifier`
+     * is set without `emailRecipientResolver` — checked eagerly to fail fast (pass
+     * `connection` for connection-local schemas). Ignored by custom resolvers.
      */
     userModelName?: string;
     /**
@@ -466,11 +543,15 @@ type MessageModel = mongoose.Model<IBaseMessage, object, IMessageMethods>;
 /**
  * Build a fresh Message schema with the given configuration.
  * Prefer this over the default `MessageSchema` export when you need
- * an email notifier, exclusions, cleanup diagnostics, or custom model names.
+ * an email notifier/recipient resolver, exclusions, cleanup diagnostics, or custom model names.
+ * For opaque string user IDs, use `schema.add()` before compiling the model to
+ * replace `fromUser`/`toUser` with trimmed String paths on both active and archive
+ * schemas; also replace archive `archivedBy`. Message `_id` stays ObjectId.
+ * The README contains the complete root-import recipe and migration policy.
  *
- * Note: when `emailNotifier` is set, the configured `userModelName` MUST
- * be registered with Mongoose before calling this function. The schema
- * factory checks this eagerly to fail fast.
+ * With `emailNotifier` and no `emailRecipientResolver`, the configured `userModelName`
+ * MUST be registered on `connection` (global Mongoose by default) before calling
+ * this function. Custom resolvers replace that adapter and need no User model.
  */
 declare function buildMessageSchema(config?: MessageSchemaConfig): mongoose.Schema<IBaseMessage, MessageModel, IMessageMethods>;
 /**
@@ -478,241 +559,7 @@ declare function buildMessageSchema(config?: MessageSchemaConfig): mongoose.Sche
  * Provided for backwards compatibility and simple use cases.
  * Use `buildMessageSchema(config)` when you need custom behavior.
  */
-declare const MessageSchema: mongoose.Schema<IBaseMessage, MessageModel, IMessageMethods, {}, {}, {}, mongoose.DefaultSchemaOptions, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-    id: string;
-}, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-    _id: mongoose.Types.ObjectId;
-} & {
-    __v: number;
-}, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-    id: string;
-} & IMessageMethods>, {
-    templateCd?: mongoose.SchemaDefinitionProperty<string, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    type?: mongoose.SchemaDefinitionProperty<MessageType, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    fromUser?: mongoose.SchemaDefinitionProperty<UserId | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    toUser?: mongoose.SchemaDefinitionProperty<UserId | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    toRoles?: mongoose.SchemaDefinitionProperty<string[], IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    senderContent?: mongoose.SchemaDefinitionProperty<IMessageContent, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    receiverContent?: mongoose.SchemaDefinitionProperty<IMessageContent, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    documents?: mongoose.SchemaDefinitionProperty<mongoose.Types.ObjectId[], IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    paymentSession?: mongoose.SchemaDefinitionProperty<string | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    paymentCd?: mongoose.SchemaDefinitionProperty<string, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    payload?: mongoose.SchemaDefinitionProperty<Record<string, unknown>, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    display?: mongoose.SchemaDefinitionProperty<Record<string, unknown>, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    clientRequestId?: mongoose.SchemaDefinitionProperty<string | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    clientRequestOwnerId?: mongoose.SchemaDefinitionProperty<string | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    clientRequestItemIndex?: mongoose.SchemaDefinitionProperty<number | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    actionState?: mongoose.SchemaDefinitionProperty<ActionLifecycleState, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    actionCd?: mongoose.SchemaDefinitionProperty<string | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    actionAttemptId?: mongoose.SchemaDefinitionProperty<string | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    actionOwnerToken?: mongoose.SchemaDefinitionProperty<string | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    actionClaimedBy?: mongoose.SchemaDefinitionProperty<string | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    actionClaimedAt?: mongoose.SchemaDefinitionProperty<Date | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    actionLeaseExpiresAt?: mongoose.SchemaDefinitionProperty<Date | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    actionFailureMessage?: mongoose.SchemaDefinitionProperty<string | null, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    createdAt?: mongoose.SchemaDefinitionProperty<Date, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-    updatedAt?: mongoose.SchemaDefinitionProperty<Date, IBaseMessage, mongoose.Document<unknown, {}, IBaseMessage, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageMethods>> | undefined;
-}, IBaseMessage>;
+declare const MessageSchema: ReturnType<typeof buildMessageSchema>;
 
 type MessageArchiveSchemaFields = IBaseMessage & {
     actionCd: string;
@@ -728,540 +575,16 @@ type MessageArchiveModel = mongoose.Model<MessageArchiveSchemaFields, object, IM
  * Build a fresh MessageArchive schema.
  * Mirrors the default Message schema but adds archive-specific fields
  * (actionCd, archivedBy, archivedAt) and no pre-save email hook.
+ * Opaque string user IDs require String overrides for `fromUser`, `toUser`, AND
+ * `archivedBy` before model compilation (and matching active-party overrides).
+ * See the README recipe; message `_id` remains ObjectId.
  */
 declare function buildMessageArchiveSchema(): mongoose.Schema<MessageArchiveSchemaFields, MessageArchiveModel, IMessageRelationshipMethods>;
 /**
  * Default MessageArchive schema. Provided for backwards compatibility.
  * Use `buildMessageArchiveSchema()` if you need a fresh instance.
  */
-declare const MessageArchiveSchema: mongoose.Schema<MessageArchiveSchemaFields, MessageArchiveModel, IMessageRelationshipMethods, {}, {}, {}, mongoose.DefaultSchemaOptions, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-    id: string;
-}, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-    actionCd: string;
-    archivedBy: unknown;
-    archivedAt: Date;
-    actionAttemptId: string | null;
-    actionNotificationState: "none" | "pending" | "sent" | "failed";
-    actionNotificationError: string | null;
-    actionNotificationAttemptedAt: Date | null;
-} & {
-    _id: mongoose.Types.ObjectId;
-} & {
-    __v: number;
-}, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-    id: string;
-} & IMessageRelationshipMethods>, {
-    templateCd?: mongoose.SchemaDefinitionProperty<string, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    type?: mongoose.SchemaDefinitionProperty<MessageType, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    fromUser?: mongoose.SchemaDefinitionProperty<UserId | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    toUser?: mongoose.SchemaDefinitionProperty<UserId | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    toRoles?: mongoose.SchemaDefinitionProperty<string[], MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    senderContent?: mongoose.SchemaDefinitionProperty<IMessageContent, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    receiverContent?: mongoose.SchemaDefinitionProperty<IMessageContent, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    documents?: mongoose.SchemaDefinitionProperty<mongoose.Types.ObjectId[], MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    paymentSession?: mongoose.SchemaDefinitionProperty<string | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    paymentCd?: mongoose.SchemaDefinitionProperty<string, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    payload?: mongoose.SchemaDefinitionProperty<Record<string, unknown>, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    display?: mongoose.SchemaDefinitionProperty<Record<string, unknown>, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    clientRequestId?: mongoose.SchemaDefinitionProperty<string | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    clientRequestOwnerId?: mongoose.SchemaDefinitionProperty<string | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    clientRequestItemIndex?: mongoose.SchemaDefinitionProperty<number | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    actionState?: mongoose.SchemaDefinitionProperty<ActionLifecycleState, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    actionCd?: mongoose.SchemaDefinitionProperty<string, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    actionAttemptId?: mongoose.SchemaDefinitionProperty<string | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    actionOwnerToken?: mongoose.SchemaDefinitionProperty<string | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    actionClaimedBy?: mongoose.SchemaDefinitionProperty<string | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    actionClaimedAt?: mongoose.SchemaDefinitionProperty<Date | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    actionLeaseExpiresAt?: mongoose.SchemaDefinitionProperty<Date | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    actionFailureMessage?: mongoose.SchemaDefinitionProperty<string | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    createdAt?: mongoose.SchemaDefinitionProperty<Date, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    updatedAt?: mongoose.SchemaDefinitionProperty<Date, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    archivedBy?: mongoose.SchemaDefinitionProperty<unknown, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    archivedAt?: mongoose.SchemaDefinitionProperty<Date, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    actionNotificationState?: mongoose.SchemaDefinitionProperty<"failed" | "none" | "pending" | "sent", MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    actionNotificationError?: mongoose.SchemaDefinitionProperty<string | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-    actionNotificationAttemptedAt?: mongoose.SchemaDefinitionProperty<Date | null, MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
-        actionCd: string;
-        archivedBy: unknown;
-        archivedAt: Date;
-        actionAttemptId: string | null;
-        actionNotificationState: "none" | "pending" | "sent" | "failed";
-        actionNotificationError: string | null;
-        actionNotificationAttemptedAt: Date | null;
-    } & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    } & IMessageRelationshipMethods>> | undefined;
-}, MessageArchiveSchemaFields>;
+declare const MessageArchiveSchema: ReturnType<typeof buildMessageArchiveSchema>;
 
 interface MessageRequestSchemaFields {
     clientRequestId: string;
@@ -1278,124 +601,7 @@ interface MessageRequestSchemaFields {
     updatedAt: Date;
 }
 declare function buildMessageRequestSchema(): mongoose.Schema<MessageRequestSchemaFields>;
-declare const MessageRequestSchema: mongoose.Schema<MessageRequestSchemaFields, mongoose.Model<MessageRequestSchemaFields, any, any, any, any, any, MessageRequestSchemaFields>, {}, {}, {}, {}, mongoose.DefaultSchemaOptions, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
-    id: string;
-}, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
-    _id: mongoose.Types.ObjectId;
-} & {
-    __v: number;
-}, "id"> & mongoose.HydratedDocumentOverrides<{
-    id: string;
-}>, {
-    clientRequestId?: mongoose.SchemaDefinitionProperty<string, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id"> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    }>> | undefined;
-    clientRequestOwnerId?: mongoose.SchemaDefinitionProperty<string, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id"> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    }>> | undefined;
-    templateCd?: mongoose.SchemaDefinitionProperty<string, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id"> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    }>> | undefined;
-    state?: mongoose.SchemaDefinitionProperty<"failed" | "pending" | "completed", MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id"> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    }>> | undefined;
-    itemCount?: mongoose.SchemaDefinitionProperty<number | null, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id"> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    }>> | undefined;
-    leaseOwnerId?: mongoose.SchemaDefinitionProperty<string | null, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id"> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    }>> | undefined;
-    leaseExpiresAt?: mongoose.SchemaDefinitionProperty<Date | null, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id"> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    }>> | undefined;
-    completedAt?: mongoose.SchemaDefinitionProperty<Date | null, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id"> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    }>> | undefined;
-    failedAt?: mongoose.SchemaDefinitionProperty<Date | null, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id"> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    }>> | undefined;
-    failureMessage?: mongoose.SchemaDefinitionProperty<string | null, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id"> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    }>> | undefined;
-    createdAt?: mongoose.SchemaDefinitionProperty<Date, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id"> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    }>> | undefined;
-    updatedAt?: mongoose.SchemaDefinitionProperty<Date, MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
-        id: string;
-    }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
-        _id: mongoose.Types.ObjectId;
-    } & {
-        __v: number;
-    }, "id"> & mongoose.HydratedDocumentOverrides<{
-        id: string;
-    }>> | undefined;
-}, MessageRequestSchemaFields>;
+declare const MessageRequestSchema: ReturnType<typeof buildMessageRequestSchema>;
 
 /**
  * Single explicit permission predicate shared by every permission boundary:
@@ -1494,6 +700,11 @@ declare function interpolateTemplate(template: MessageTemplate | RegisteredMessa
 /**
  * Email provider interface.
  * Host app implements this to send email notifications.
+ * Pass `provider.sendNotification.bind(provider)` as `buildMessageSchema`'s
+ * `emailNotifier`; methods are not automatically bound. Recipient lookup is
+ * configured separately with `emailRecipientResolver` (local User.email by
+ * default). Delivery is best-effort for new session-free saves, not a durable
+ * outbox; failures are observed through `onEmailDeliveryFailure`.
  */
 interface EmailProvider {
     sendNotification(to: string, title: string, body: string): Promise<void>;
@@ -1512,6 +723,14 @@ declare class NoopEmailProvider implements EmailProvider {
  * Host apps implement this to handle payment sessions for messages
  * that require payment (e.g. Stripe, Adyen, Paddle).
  *
+ * Every fresh item's nonempty `item.paymentCd || template.paymentCd || ''`
+ * requires a session, even with no recipients. Empty item codes inherit the
+ * template code; codes are passed through without trimming. Absent/null
+ * providers raise `PaymentProviderRequiredError`; code-free creation and
+ * completed replay (including legacy sessionless records) need no provider.
+ * Session creation is not proof of payment: completion, capture, webhooks, and
+ * payment-based business authorization remain host/provider responsibilities.
+ *
  * Message creation may create external sessions before MongoDB commit. If any
  * prepared item, model/session setup step, or idempotent batch transaction
  * fails before commit, `MessageService` calls `expireSession()` for every
@@ -1543,9 +762,12 @@ declare class NoopEmailProvider implements EmailProvider {
  */
 interface PaymentProvider {
     /**
-     * Create a checkout/session for the given user and pricing code.
-     * Return the session id, or `null` to indicate the session could not
-     * be created (the message creation flow will throw in that case).
+     * Create one checkout/session per payment-bearing prepared item, independently
+     * of recipients, outside retryable transaction callbacks. `user` is
+     * `(payerUser || user)._id`, not the prepared sender or recipient; only the
+     * item's `priceArgs` is forwarded. Return a nonempty session id. A null/empty
+     * result throws `Error('payment session creation failed')`; provider rejections
+     * propagate unchanged (unless known-session compensation itself fails).
      */
     createSession(user: UserId, code: string, priceArgs?: Record<string, unknown>): Promise<string | null>;
     /**
@@ -1560,9 +782,11 @@ interface PaymentProvider {
     refundPayment(sessionId: string): Promise<void>;
 }
 /**
- * No-op payment provider that returns null for session creation
- * and does nothing for expire/refund. Useful for apps that don't use payments
- * or for tests.
+ * No-op payment provider that returns null for session creation and does nothing
+ * for expire/refund. It cannot satisfy a nonempty payment code: fresh paid items
+ * fail with `Error('payment session creation failed')`, even without recipients.
+ * Code-free applications may omit the provider entirely; tests may use this
+ * implementation to exercise the configured-provider null-return contract.
  */
 declare class NoopPaymentProvider implements PaymentProvider {
     createSession(_user: UserId, _code: string, _priceArgs?: Record<string, unknown>): Promise<string | null>;
@@ -1592,6 +816,18 @@ declare class ActionNotAllowedError extends Error {
     static [Symbol.hasInstance](value: unknown): boolean;
     constructor();
 }
+/**
+ * Invalid submitted command rejected by a pure `MessageAction.parseInput` hook.
+ * Root-exported with mixed ESM/CommonJS `instanceof` support. HTTP returns only
+ * the fixed `invalid action input` message (400), never this diagnostic/cause or
+ * an attempt ID. Fresh pre-handler claims are released; retry attempts are kept.
+ * Throwing this inside a handler retains the ordinary `ActionRetryableError`
+ * contract because business effects may already have occurred.
+ */
+declare class ActionInputValidationError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(message?: string);
+}
 declare class InvalidMessageUserError extends Error {
     static [Symbol.hasInstance](value: unknown): boolean;
     constructor(message?: string);
@@ -1662,6 +898,20 @@ declare class MessageModelResolutionError extends Error {
     connectionName: string;
     constructor(role: MessageModelRole, modelName: string, connectionName: string, cause?: unknown);
 }
+/**
+ * Fresh template creation requires a payment provider for every nonempty
+ * effective `paymentCd`, regardless of recipients. Absent/null providers throw
+ * this server-configuration error before the item's write. Code-free items and
+ * completed replays (including legacy sessionless records) need no provider.
+ *
+ * Root-exported with mixed ESM/CommonJS `instanceof` support. Routes use the
+ * sanitized HTTP 500 path; no template, code, payer, or session details are carried.
+ * Configured-provider rejections and null-return errors retain their own contracts.
+ */
+declare class PaymentProviderRequiredError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor();
+}
 declare class PaymentSessionCompensationError extends Error {
     static [Symbol.hasInstance](value: unknown): boolean;
     sessionId: string;
@@ -1700,6 +950,11 @@ interface MessageServiceOptions {
     getModel?: (name: string) => mongoose.Model<unknown>;
     connection?: mongoose.Connection;
     modelNames?: Partial<MessageServiceModelNames>;
+    /**
+     * Required for fresh items with a nonempty effective `paymentCd`, even without
+     * recipients; absent/null throws `PaymentProviderRequiredError`. Optional for
+     * code-free items and completed replays, including legacy sessionless records.
+     */
     paymentProvider?: PaymentProvider | null;
     /**
      * Called when the service cannot expire an external payment session that was
@@ -1713,6 +968,11 @@ interface MessageServiceOptions {
      * Configure `buildMessageSchema` separately for direct document `archive()`.
      */
     onTransactionCleanupFailure?: MessageTransactionCleanupFailureObserver;
+    /**
+     * Fallback roles for `createMessage` when prepared `toUser` is absent and
+     * `toRoles` is omitted or empty (`[]` does not suppress fallback).
+     * Explicit roles are preserved even alongside `toUser`. Defaults to `[]`.
+     */
     adminRoles?: string[];
     registry?: TemplateRegistry;
     /**
@@ -1724,6 +984,22 @@ interface MessageServiceOptions {
      * Hard upper bound for `listMessages` limit to prevent abuse. Defaults to 100.
      */
     maxListLimit?: number;
+    /**
+     * Processing lease for each action acquisition. Defaults to 30000 ms.
+     * Only omission or `undefined` selects the default; `null` is invalid.
+     * Must be a finite safe integer in `[1, MAX_MESSAGE_SERVICE_TIMEOUT_MS]` ms
+     * (`2147483647` maximum); invalid values throw `InvalidMessageServiceOptionError`
+     * at construction. Route construction forwards this option; injected routes
+     * require configuring it on the supplied service instead.
+     *
+     * Expiry permits same-action takeover; it does not cancel the handler or
+     * automatically reject the still-current owner's completion/failure. Takeover
+     * retains `actionAttemptId` and rotates the owner token to fence stale writes.
+     * No heartbeat or renewal is performed. Applies to new acquisitions only;
+     * existing persisted deadlines are unchanged. Deduplicate external effects by
+     * `actionAttemptId`, including when handlers overlap after expiry.
+     */
+    actionLeaseMs?: number;
     /**
      * How long a pending idempotent create reservation lease remains live before
      * another caller may atomically take it over. Defaults to 30000 ms.
@@ -1808,6 +1084,9 @@ declare const GENERIC_NOTIFICATION_TEMPLATE_CD = "__generic-notification__";
  * ObjectId by callers and normalized to their hex string only where a string
  * scope/query key is required.
  *
+ * This predicate checks only the id. `requireMessageUserId` also validates
+ * optional principal roles: omitted/undefined or an array of strings.
+ *
  * `findMessage`/`findMessageOrThrow` and `createNotification` are trusted
  * host-level operations and intentionally do not take a principal; they are
  * not part of this contract.
@@ -1816,8 +1095,15 @@ declare function isValidMessageUserId(id: unknown): id is string | mongoose.Type
 /**
  * Assert a user-facing principal and return its normalized string identity.
  * Throws `InvalidMessageUserError` for missing/null/empty/numeric/array/
- * plain-object ids. String ids are trimmed; ObjectId ids become their hex
- * string. The caller's original `MessageUser` object (and its `_id` type) is
+ * plain-object ids, or malformed `roles` (anything except undefined or an
+ * array containing only strings). Role strings retain their exact values;
+ * no coercion, trimming, or substring matching is applied. String ids are
+ * trimmed; ObjectId ids become their hex string.
+ * Case is preserved even for hex-looking strings: request scopes are textual,
+ * so uppercase hex and lowercase hex remain separate legacy-compatible scopes.
+ * Relationship matching against a stored native ObjectId accepts either case;
+ * stored String parties use exact trimmed equality. See the README user-ID recipe.
+ * The caller's original `MessageUser` object (and its `_id` type) is
  * left untouched so ObjectId-backed schemas keep their native type.
  */
 declare function requireMessageUserId(user: unknown): string;
@@ -1875,10 +1161,25 @@ declare class MessageService {
      *
      * 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`)
+     * arrays, and plain objects are rejected with `InvalidMessageUserError`),
+     * and optional `roles` must be undefined or an array of strings,
      * before any template, provider, or model effect runs. Both the
      * idempotent (`clientRequestId`) and direct branches enforce this.
      *
+     * Each `PrepareResult.documents` selects that item's attachments; `[]` clears
+     * them. Omission/undefined retains the original caller `payload.documents`
+     * fallback, independently of the prepared business payload. Selected arrays
+     * are copied per item without mutating caller/preparation arrays.
+     *
+     * Each fresh item's `item.paymentCd || template.paymentCd || ''` requests a
+     * session when nonempty, independently of recipients. An empty item override
+     * inherits the template code. Absent/null providers throw
+     * `PaymentProviderRequiredError`; configured-provider rejections propagate and
+     * null/empty session returns throw `Error('payment session creation failed')`.
+     * The payer remains `(payerUser || user)._id`, not the prepared sender/recipient.
+     * Direct batches retain committed prefixes; idempotent batches commit atomically
+     * and compensate all known uncommitted sessions on failure.
+     *
      * 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
@@ -1944,7 +1245,8 @@ declare class MessageService {
      * 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 }`.
+     * contract before model resolution. Returns `IMessage[]` ordered by
+     * `{ createdAt: -1, _id: -1 }`.
      */
     listMessages(params: {
         user: MessageUser;
@@ -1956,7 +1258,8 @@ declare class MessageService {
      * 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.
+     * User-facing operation: validates `user` via the shared principal contract
+     * before model resolution.
      */
     countMessages(user: MessageUser): Promise<number>;
     /**
@@ -1997,12 +1300,28 @@ declare class MessageService {
      * Execute an action with a durable claim, stable handler attempt key,
      * transactional archive, and post-commit sender notification status.
      *
+     * `actionLeaseMs` controls when a same-action retry may take over. Expiry alone
+     * does not cancel the handler or reject a still-current owner; takeover fences
+     * stale completion/failure writes with `ActionConflictError`. There is no
+     * heartbeat or renewal; external effects must deduplicate by `actionAttemptId`.
+     *
      * User-facing operation: `data.user` is validated before any template or
-     * model effect. Authorization and handler selection bind to the persisted
+     * model effect. Handler users contain only the documented `MessageUser`
+     * fields, read explicitly (including getters), with a copied roles array;
+     * the caller's user and original `req` are not modified.
+     * 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`.
+     * `data.input` is explicit submitted data, never inferred from `req`. The
+     * current claimed action's optional synchronous pure `parseInput` supplies
+     * `ctx.input` after authorization. Invalid input throws
+     * `ActionInputValidationError`; unexpected parser failures preserve their
+     * cause as server errors. Both use fenced pre-handler release: fresh claims
+     * return to active, retries retain their stable attempt/action as retryable.
+     * Hosts own input bounds, runtime validation, and durable command/result
+     * binding at first host reservation (not at package claim).
      * Returns the handler's value (`unknown`; templates
      * document their own shape).
      */
@@ -2010,6 +1329,8 @@ declare class MessageService {
         message: IMessage | IMessageArchive;
         user: MessageUser;
         permissions?: Record<string, boolean>;
+        /** Submitted command; HTTP supplies its body. Separate from stored/action payloads. */
+        input?: unknown;
         req?: unknown;
     }): Promise<unknown>;
     private resolveModel;
@@ -2023,6 +1344,7 @@ declare class MessageService {
     private compensatePaymentSessions;
     private compensatePaymentSession;
     private buildActionContext;
+    private parseActionInput;
     private claimAction;
     /**
      * Relationship/permission policy for archived outcomes.
@@ -2064,6 +1386,7 @@ declare class MessageService {
     private normalizeListSkip;
     private buildClientRequestScope;
     private requireUserId;
+    private buildAuthorizedUser;
     private findByClientRequestScope;
     private findArchivedByClientRequestScope;
     /**
@@ -2169,6 +1492,9 @@ interface MessageRoutesBehaviorOptions {
      * require this extractor to return a user with a valid `_id` (non-empty
      * string or ObjectId; numbers, arrays, and plain objects are rejected)
      * before any service, template, payment, model, or action side effect runs.
+     * Optional `roles` must be undefined or an array containing only strings;
+     * malformed roles also produce 401 before service/model lookup.
+     * The original request and extracted user are passed through unchanged.
      * Shares the service's principal-validation contract.
      */
     getUser?: (req: Request) => MessageUser | undefined;
@@ -2195,7 +1521,7 @@ interface MessageRoutesBehaviorOptions {
  * Convenience-construction path: routes build and own a `MessageService`
  * from the full service option set. `service` must be absent; every other
  * service knob (`getModel`, `connection`, `modelNames`, payment, `registry`,
- * list limits, and `clientRequest*` timing/test hooks) is forwarded verbatim
+ * list limits, `actionLeaseMs`, and `clientRequest*` timing/test hooks) is forwarded verbatim
  * to `new MessageService(...)` so the route service never drifts behind the
  * direct-service configuration surface.
  */
@@ -2230,6 +1556,7 @@ interface MessageRoutesInjectionOptions extends MessageRoutesBehaviorOptions {
     registry?: never;
     defaultListLimit?: never;
     maxListLimit?: never;
+    actionLeaseMs?: never;
     clientRequestLeaseMs?: never;
     clientRequestWaitMs?: never;
     clientRequestPollMs?: never;
@@ -2286,4 +1613,4 @@ declare function createMessageRoutes(options: MessageRoutesOptions): {
     service: MessageService;
 };
 
-export { type ActionConfirmation, ActionConflictError, type ActionContext, type ActionLifecycleState, ActionNotAllowedError, ActionNotFoundError, ActionNotificationPendingError, type ActionNotificationState, ActionRetryableError, ActionTemplateMismatchError, BaseMessageFields, ClientRequestFailedError, ClientRequestInconsistentStateError, ClientRequestPendingError, type EmailDeliveryFailureEvent, type EmailDeliveryFailureStage, type EmailNotifier, type EmailProvider, GENERIC_NOTIFICATION_TEMPLATE_CD, type IBaseMessage, type IMessage, type IMessageArchive, type IMessageContent, type IMessageMethods, type InterpolatedAction, type InterpolatedContent, type InterpolationResult, InvalidClientRequestIdError, InvalidMessageServiceOptionError, InvalidMessageUserError, InvalidPaginationValueError, MAX_MESSAGE_SERVICE_TIMEOUT_MS, MESSAGE_ARCHIVE_MODEL_NAME, MESSAGE_MODEL_NAME, MESSAGE_REQUEST_MODEL_NAME, type MessageAction, MessageArchiveSchema, MessageArchivedError, MessageContentSchema, MessageModelResolutionError, MessageNotFoundError, MessageRequestSchema, type MessageRoutesBehaviorOptions, type MessageRoutesConstructionOptions, type MessageRoutesInjectionOptions, type MessageRoutesOptions, MessageSchema, type MessageSchemaConfig, MessageService, type MessageServiceModelNames, type MessageServiceOptions, type MessageTemplate, type MessageTransactionCleanupFailureEvent, type MessageTransactionCleanupFailureObserver, MessageTransactionRequiredError, type MessageType, type MessageUser, NoopEmailProvider, NoopPaymentProvider, type PaymentCompensationFailureEvent, type PaymentProvider, PaymentSessionCompensationAggregateError, PaymentSessionCompensationError, type PaymentSessionCompensationFailure, type PrepareContext, type PrepareResult, type PublicMessageDto, type PublicMessageParty, type PublicMessageSource, type RegisteredMessageAction, type RegisteredMessageTemplate, type RegisteredUiTemplate, type SenderNotificationContent, TemplateNotFoundError, TemplateRegistry, TemplateRegistryValidationError, type UiTemplate, type UserId, type Usertype, buildMessageArchiveSchema, buildMessageRequestSchema, buildMessageSchema, createMessageRoutes, defaultRegistry, filterActions, hasExplicitPermissionGrant, includesAction, interpolateMessageContent, interpolateTemplate, isActionAllowed, isValidMessageUserId, requireMessageUserId, resolveUiTemplate, serializePublicMessage };
+export { type ActionConfirmation, ActionConflictError, type ActionContext, ActionInputValidationError, type ActionLifecycleState, ActionNotAllowedError, ActionNotFoundError, ActionNotificationPendingError, type ActionNotificationState, ActionRetryableError, ActionTemplateMismatchError, BaseMessageFields, ClientRequestFailedError, ClientRequestInconsistentStateError, ClientRequestPendingError, type EmailDeliveryFailureEvent, type EmailDeliveryFailureStage, type EmailNotifier, type EmailProvider, type EmailRecipientResolver, type EmailRecipientResolverContext, GENERIC_NOTIFICATION_TEMPLATE_CD, type IBaseMessage, type IMessage, type IMessageArchive, type IMessageContent, type IMessageMethods, type InterpolatedAction, type InterpolatedContent, type InterpolationResult, InvalidClientRequestIdError, InvalidMessageServiceOptionError, InvalidMessageUserError, InvalidPaginationValueError, MAX_MESSAGE_SERVICE_TIMEOUT_MS, MESSAGE_ARCHIVE_MODEL_NAME, MESSAGE_MODEL_NAME, MESSAGE_REQUEST_MODEL_NAME, type MessageAction, MessageArchiveSchema, MessageArchivedError, MessageContentSchema, MessageModelResolutionError, MessageNotFoundError, MessageRequestSchema, type MessageRoutesBehaviorOptions, type MessageRoutesConstructionOptions, type MessageRoutesInjectionOptions, type MessageRoutesOptions, MessageSchema, type MessageSchemaConfig, MessageService, type MessageServiceModelNames, type MessageServiceOptions, type MessageTemplate, type MessageTransactionCleanupFailureEvent, type MessageTransactionCleanupFailureObserver, MessageTransactionRequiredError, type MessageType, type MessageUser, NoopEmailProvider, NoopPaymentProvider, type PaymentCompensationFailureEvent, type PaymentProvider, PaymentProviderRequiredError, PaymentSessionCompensationAggregateError, PaymentSessionCompensationError, type PaymentSessionCompensationFailure, type PrepareContext, type PrepareResult, type PublicMessageDto, type PublicMessageParty, type PublicMessageSource, type RegisteredMessageAction, type RegisteredMessageTemplate, type RegisteredUiTemplate, type SenderNotificationContent, TemplateNotFoundError, TemplateRegistry, TemplateRegistryValidationError, type UiTemplate, type UserId, type Usertype, buildMessageArchiveSchema, buildMessageRequestSchema, buildMessageSchema, createMessageRoutes, defaultRegistry, filterActions, hasExplicitPermissionGrant, includesAction, interpolateMessageContent, interpolateTemplate, isActionAllowed, isValidMessageUserId, requireMessageUserId, resolveUiTemplate, serializePublicMessage };