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

package/index.d.ts

@@ -2,6 +2,27 @@ import mongoose from 'mongoose';
 import JsonRouter from '@web-ts-toolkit/express-json-router';
 import { Request, Response, NextFunction } from 'express';
 
+/** Diagnostics for a package-owned session whose `endSession()` rejected. */
+type MessageTransactionCleanupFailureEvent = {
+    operation: 'createBatch' | 'actionArchive' | 'directArchive';
+    stage: 'endSession';
+    error: unknown;
+} & ({
+    outcome: 'committed';
+    originalError?: never;
+} | {
+    /** Transaction rejected; this does not certify rollback of an ambiguous commit. */
+    outcome: 'failed';
+    originalError: unknown;
+});
+/**
+ * Best-effort diagnostic observer, awaited after session cleanup rejects.
+ * Throws/rejections are swallowed to preserve the committed result or primary
+ * transaction error. Keep it bounded; it is not a retry/compensation hook.
+ * Caller-owned sessions are never ended or reported by the package.
+ */
+type MessageTransactionCleanupFailureObserver = (event: MessageTransactionCleanupFailureEvent) => void | Promise<void>;
+
 interface PrepareContext {
     user: MessageUser;
     roles: string[];
@@ -87,6 +108,40 @@ interface MessageTemplate {
     prepareMessage: (ctx: PrepareContext) => Promise<PrepareResult | PrepareResult[] | null>;
     actions: MessageAction[];
 }
+/**
+ * Readonly uiTemplate view matching the registry freeze depth: a plain string
+ * passes through, while object forms are shallow-frozen at registration.
+ */
+type RegisteredUiTemplate = string | Readonly<{
+    sender?: string;
+    receiver?: string;
+}>;
+/**
+ * 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
+ * identity and remain callable.
+ */
+type RegisteredMessageAction = Readonly<Omit<MessageAction, 'confirmation' | 'payload'>> & {
+    readonly confirmation?: Readonly<ActionConfirmation>;
+    readonly payload?: Readonly<Record<string, unknown>>;
+};
+/**
+ * Readonly template view matching the registry freeze depth: the top-level
+ * snapshot, `senderContent`/`receiverContent`, object `uiTemplate`s, the
+ * action array, and each action plus its `confirmation`/`payload` are frozen.
+ * Mutating a registered view throws at runtime; register a replacement
+ * template to change behavior.
+ *
+ * Registration inputs stay author-friendly and mutable (`MessageTemplate`);
+ * only registry outputs use this readonly view.
+ */
+type RegisteredMessageTemplate = Readonly<Omit<MessageTemplate, 'senderContent' | 'receiverContent' | 'uiTemplate' | 'actions'>> & {
+    readonly senderContent: Readonly<MessageTemplate['senderContent']>;
+    readonly receiverContent: Readonly<MessageTemplate['receiverContent']>;
+    readonly uiTemplate: RegisteredUiTemplate;
+    readonly actions: readonly RegisteredMessageAction[];
+};
 interface InterpolatedContent {
     title: string;
     long: string;
@@ -139,6 +194,9 @@ declare class TemplateRegistry {
     private templates;
     /**
      * 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: MessageTemplate): void;
     /**
@@ -147,8 +205,13 @@ declare class TemplateRegistry {
     registerAll(templates: MessageTemplate[]): void;
     /**
      * 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: string): MessageTemplate | undefined;
+    find(templateCd: string): RegisteredMessageTemplate | undefined;
     /**
      * Check if a template exists.
      */
@@ -159,8 +222,10 @@ declare class TemplateRegistry {
     getTemplateCodes(): string[];
     /**
      * Get all registered templates.
+     *
+     * Returns readonly `RegisteredMessageTemplate` views; see `find()`.
      */
-    getAll(): MessageTemplate[];
+    getAll(): RegisteredMessageTemplate[];
     /**
      * Remove a template by templateCd.
      */
@@ -204,10 +269,30 @@ interface MessageUser {
     displayName?: string;
 }
 interface IMessageRelationshipMethods {
+    /** Match a string/ObjectId or populated party's `_id`; missing references never match. */
     isSender(user: MessageUser): boolean;
+    /** Match the recipient identity (including populated `_id`) or an explicit recipient role. */
     isReceiver(user: MessageUser): boolean;
 }
 interface IMessageMethods extends IMessageRelationshipMethods {
+    /**
+     * Trusted host-level archival primitive: atomically moves the active message
+     * into the archive collection on the document's owning connection.
+     *
+     * The host must authorize before calling (no sender/receiver, permission, or
+     * condition checks run here). Invalid `actionCd` throws
+     * `TemplateNotFoundError`/`ActionNotFoundError`; an invalid `archivedBy`
+     * throws `InvalidMessageUserError` — never a silent no-op success. A live
+     * in-flight service claim (`processing` without an expired lease) throws
+     * `ActionConflictError` and steals nothing. Repeat calls throw
+     * `MessageArchivedError` (archive copy exists) or `MessageNotFoundError`.
+     * Deployments without transaction support throw
+     * `MessageTransactionRequiredError` before writing anything.
+     * Confirmed commit resolves even if session cleanup rejects; configure
+     * `buildMessageSchema({ onTransactionCleanupFailure })` for diagnostics.
+     * Observer failures cannot change the outcome. An attached `$session()` is
+     * borrowed and never ended by this method; its caller owns cleanup.
+     */
     archive(actionCd: string, archivedBy: UserId, registry: TemplateRegistry): Promise<void>;
 }
 /**
@@ -237,6 +322,7 @@ interface IBaseMessage {
     actionState: ActionLifecycleState;
     actionCd: string | null;
     actionAttemptId: string | null;
+    actionOwnerToken: string | null;
     actionClaimedBy: string | null;
     actionClaimedAt: Date | null;
     actionLeaseExpiresAt: Date | null;
@@ -253,6 +339,7 @@ type IMessageArchive = mongoose.Document<unknown, MongooseQueryHelpers, IMessage
     archivedBy: UserId;
     archivedAt: Date;
     actionAttemptId: string | null;
+    actionOwnerToken: string | null;
     actionNotificationState: ActionNotificationState;
     actionNotificationError: string | null;
     actionNotificationAttemptedAt: Date | null;
@@ -322,7 +409,11 @@ interface MessageSchemaConfig {
      * send a best-effort email notification to the recipient. Pass `null` (the
      * default) to disable.
      *
-     * When `null`, no pre-save hook is registered at all.
+     * When `null`, no save hooks are registered at all. 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).
      */
     emailNotifier?: EmailNotifier | null;
     /**
@@ -340,11 +431,15 @@ interface MessageSchemaConfig {
     emailNotificationExclusions?: string[];
     /**
      * Name of the Mongoose model that holds the recipient user records.
-     * Defaults to `'User'`. The pre-save hook uses `mongoose.model(name)`
-     * to look up the recipient's email address.
+     * 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 with Mongoose before the first save —
-     * `buildMessageSchema` does a sanity check to give a clear error if not.
+     * 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).
      */
     userModelName?: string;
     /**
@@ -358,12 +453,20 @@ interface MessageSchemaConfig {
      * Defaults to `'MessageArchive'`. Used by the `archive()` instance method.
      */
     archiveModelName?: string;
+    /**
+     * Best-effort diagnostics for `endSession()` rejection after direct `archive()`.
+     * Preserves committed success or the primary transaction error even when the
+     * observer throws/rejects. Awaited; keep it bounded. Borrowed document sessions
+     * remain caller-owned and are not ended/reported. Service writes use the
+     * separate `MessageServiceOptions.onTransactionCleanupFailure` observer.
+     */
+    onTransactionCleanupFailure?: MessageTransactionCleanupFailureObserver;
 }
 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, or custom model names.
+ * an email notifier, exclusions, cleanup diagnostics, or custom model names.
  *
  * Note: when `emailNotifier` is set, the configured `userModelName` MUST
  * be registered with Mongoose before calling this function. The schema
@@ -371,7 +474,7 @@ type MessageModel = mongoose.Model<IBaseMessage, object, IMessageMethods>;
  */
 declare function buildMessageSchema(config?: MessageSchemaConfig): mongoose.Schema<IBaseMessage, MessageModel, IMessageMethods>;
 /**
- * Default Message schema with no email notifier and no pre-save hook.
+ * Default Message schema with no email notifier and no save hooks.
  * Provided for backwards compatibility and simple use cases.
  * Use `buildMessageSchema(config)` when you need custom behavior.
  */
@@ -546,6 +649,15 @@ declare const MessageSchema: mongoose.Schema<IBaseMessage, MessageModel, IMessag
     }, "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 & {
@@ -945,6 +1057,23 @@ declare const MessageArchiveSchema: mongoose.Schema<MessageArchiveSchemaFields,
     }, "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 & {
@@ -1081,7 +1210,7 @@ declare const MessageArchiveSchema: mongoose.Schema<MessageArchiveSchemaFields,
     }, "id" | keyof IMessageRelationshipMethods> & mongoose.HydratedDocumentOverrides<{
         id: string;
     } & IMessageRelationshipMethods>> | undefined;
-    actionNotificationState?: mongoose.SchemaDefinitionProperty<"none" | "pending" | "sent" | "failed", MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
+    actionNotificationState?: mongoose.SchemaDefinitionProperty<"failed" | "none" | "pending" | "sent", MessageArchiveSchemaFields, mongoose.Document<unknown, {}, MessageArchiveSchemaFields, {
         id: string;
     }, mongoose.DefaultSchemaOptions> & Omit<IBaseMessage & {
         actionCd: string;
@@ -1185,7 +1314,7 @@ declare const MessageRequestSchema: mongoose.Schema<MessageRequestSchemaFields,
     }, "id"> & mongoose.HydratedDocumentOverrides<{
         id: string;
     }>> | undefined;
-    state?: mongoose.SchemaDefinitionProperty<"pending" | "failed" | "completed", MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
+    state?: mongoose.SchemaDefinitionProperty<"failed" | "pending" | "completed", MessageRequestSchemaFields, mongoose.Document<unknown, {}, MessageRequestSchemaFields, {
         id: string;
     }, mongoose.DefaultSchemaOptions> & Omit<MessageRequestSchemaFields & {
         _id: mongoose.Types.ObjectId;
@@ -1268,15 +1397,68 @@ declare const MessageRequestSchema: mongoose.Schema<MessageRequestSchemaFields,
     }>> | undefined;
 }, MessageRequestSchemaFields>;
 
+/**
+ * Single explicit permission predicate shared by every permission boundary:
+ * UI filtering (`filterActions`), action execution (`isActionAllowed`), and
+ * the route's admin read-only lookup.
+ *
+ * A grant requires an **own** property of the permissions map whose value is
+ * strictly `true`. Inherited properties (e.g. `constructor`, `toString`,
+ * or custom keys from a prototype chain — including the default
+ * `Object.prototype`) are denied, as are truthy non-booleans (`1`, `"true"`,
+ * `{}`, ...), `false`, and absent keys.
+ *
+ * Normal object literals and null-prototype maps (`Object.create(null)`,
+ * including JSON-parsed or `Object.assign`-built maps with own properties)
+ * both work: the check uses `Object.prototype.hasOwnProperty.call`, so it is
+ * safe for maps containing a `__proto__` key and for maps without a
+ * prototype. Non-object permission containers (`null`, `undefined`,
+ * primitives, arrays) never grant.
+ *
+ * Tightening note for custom `getPermissions` extractors: extractors that
+ * previously relied on inherited or truthy non-boolean values must now return
+ * own properties set to boolean `true`; anything else is treated as denied.
+ */
+declare function hasExplicitPermissionGrant(permissions: Record<string, boolean> | undefined | null, key: string): boolean;
+/**
+ * Render sender/receiver content only, without evaluating action predicates.
+ *
+ * Creation uses this path with `PrepareResult.templateData`: content is a
+ * function of preparation output only. Action `condition` predicates are never
+ * invoked here, so a condition that accesses persisted message fields (e.g.
+ * `message.payload.ready`) cannot fail creation. Action labels/confirmations
+ * are a separate concern rendered from persisted `message.payload` at listing
+ * time (see `filterActions`); there is deliberately no unified
+ * interpolation-data feature.
+ *
+ * Escaping/trusted-template semantics match `interpolateTemplate`: Handlebars
+ * with `noEscape: true`, plain-text output, trusted template strings only.
+ */
+declare function interpolateMessageContent(template: Pick<MessageTemplate | RegisteredMessageTemplate, 'senderContent' | 'receiverContent'>, data: Record<string, unknown>): Pick<InterpolationResult, 'senderContent' | 'receiverContent'>;
+/**
+ * Resolve the uiTemplate for a usertype without evaluating actions.
+ * Read-only/admin/archive listings use this plus an empty action list so
+ * `condition` functions are never invoked merely to discard their results.
+ *
+ * Accepts both mutable author inputs and frozen registry views.
+ */
+declare function resolveUiTemplate(uiTemplate: UiTemplate | RegisteredMessageTemplate['uiTemplate'], usertype: Usertype): string;
 /**
  * Apply the standard set of action filters (usertype match, permission, condition).
  * This is the single source of truth used by both the template engine (for UI)
  * and the server-side action handler (for authorization).
  *
+ * Permission gating uses {@link hasExplicitPermissionGrant}: only an own
+ * property strictly equal to `true` grants access.
+ *
  * The `name` and confirmation `title`/`message`/`notesLabel` strings are
- * compiled against the same `data` passed to `interpolateTemplate`.
+ * compiled against the persisted `message.payload` snapshot passed as `data`
+ * by `getActions` (via `interpolateTemplate`). This is intentionally different
+ * from message content, which is rendered at creation time from
+ * `PrepareResult.templateData`. Missing values in either source render as
+ * empty strings via Handlebars.
  */
-declare function filterActions(actions: MessageAction[], usertype: Usertype, options?: {
+declare function filterActions(actions: readonly (MessageAction | RegisteredMessageAction)[], usertype: Usertype, options?: {
     permissions?: Record<string, boolean>;
     message?: Record<string, unknown>;
     data?: Record<string, unknown>;
@@ -1285,15 +1467,26 @@ declare function filterActions(actions: MessageAction[], usertype: Usertype, opt
  * Check if the given user is allowed to execute the action on the given message.
  * Returns true if the action is permitted, false otherwise.
  * Mirrors the `filterActions` logic exactly so the UI and the server agree.
+ *
+ * Permission gating uses {@link hasExplicitPermissionGrant}: only an own
+ * property strictly equal to `true` grants access.
  */
-declare function isActionAllowed(action: MessageAction, user: MessageUser, message: IMessage | IMessageArchive, options?: {
+declare function isActionAllowed(action: MessageAction | RegisteredMessageAction, user: MessageUser, message: IMessage | IMessageArchive, options?: {
     permissions?: Record<string, boolean>;
 }): boolean;
 /**
  * Interpolate a template's sender/receiver content and filter actions
  * for the given usertype (sender or receiver).
+ *
+ * Preserved public combined helper: content is rendered from `data`
+ * (callers pass `templateData` at creation via `interpolateMessageContent`,
+ * or persisted `message.payload` at listing time), while action predicates
+ * receive the documented `message` context and action labels/confirmations
+ * compile against `data`. Creation and read-only/admin/archive paths must use
+ * `interpolateMessageContent`/`resolveUiTemplate` directly so conditions are
+ * not evaluated unnecessarily.
  */
-declare function interpolateTemplate(template: MessageTemplate, data: Record<string, unknown>, usertype: Usertype, options?: {
+declare function interpolateTemplate(template: MessageTemplate | RegisteredMessageTemplate, data: Record<string, unknown>, usertype: Usertype, options?: {
     permissions?: Record<string, boolean>;
     message?: Record<string, unknown>;
 }): InterpolationResult;
@@ -1319,13 +1512,30 @@ declare class NoopEmailProvider implements EmailProvider {
  * Host apps implement this to handle payment sessions for messages
  * that require payment (e.g. Stripe, Adyen, Paddle).
  *
- * Message creation may create external sessions before MongoDB commit. If the
- * message write or idempotent batch transaction fails, `MessageService` calls
- * `expireSession()` for every newly created uncommitted session. Providers must
- * make expiration idempotent because callers may retry cleanup after ambiguous
- * network or provider failures. If expiration itself fails, message creation
- * fails with `PaymentSessionCompensationError` and the optional service hook is
- * invoked for observability.
+ * 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
+ * newly created uncommitted session tracked from preparation through the
+ * commit attempt — including sessions from earlier batch items when a later
+ * item's provider/render step fails, and sessions left uncommitted by model
+ * resolution, `startSession()`, persistence, or rollback failures. Every
+ * known session is attempted even when an earlier expiration or the
+ * `onPaymentCompensationFailure` observer fails; multi-session batches then
+ * throw `PaymentSessionCompensationAggregateError` (a
+ * `PaymentSessionCompensationError` carrying every per-session failure in
+ * `failures` with the triggering error as `originalError`), while a lone
+ * session keeps the single-session `PaymentSessionCompensationError` shape.
+ * Providers must make expiration idempotent because callers may retry cleanup
+ * after ambiguous network or provider failures. Committed sessions are never
+ * expired because post-commit housekeeping failed; a completed same-scope
+ * retry replays the committed batch without creating replacement sessions.
+ * Non-idempotent sequential creation keeps per-item semantics: only the
+ * failing item is compensated, already-committed items are retained.
+ * Process death before a returned session is recorded, or any ambiguous
+ * provider/commit outcome this process cannot observe, must be reconciled
+ * with the provider out of band. If expiration itself fails, message creation
+ * fails with the compensation error and the optional service hook is invoked
+ * once per failed session for observability.
  *
  * `priceArgs` is intentionally a free-form `Record<string, unknown>` so
  * providers can accept their own metadata (currency, line items, etc.).
@@ -1360,67 +1570,8 @@ declare class NoopPaymentProvider implements PaymentProvider {
     refundPayment(_sessionId: string): Promise<void>;
 }
 
-interface MessageServiceOptions {
-    getModel?: (name: string) => mongoose.Model<unknown>;
-    connection?: mongoose.Connection;
-    modelNames?: Partial<MessageServiceModelNames>;
-    paymentProvider?: PaymentProvider | null;
-    /**
-     * Called when the service cannot expire an external payment session that was
-     * created for a message batch that did not commit.
-     */
-    onPaymentCompensationFailure?: (event: PaymentCompensationFailureEvent) => void | Promise<void>;
-    adminRoles?: string[];
-    registry?: TemplateRegistry;
-    /**
-     * Maximum number of messages returned by `listMessages` when no explicit
-     * limit is provided. Defaults to 50.
-     */
-    defaultListLimit?: number;
-    /**
-     * Hard upper bound for `listMessages` limit to prevent abuse. Defaults to 100.
-     */
-    maxListLimit?: number;
-    /**
-     * How long a pending idempotent create reservation lease remains live before
-     * another caller may atomically take it over. Defaults to 30000 ms.
-     */
-    clientRequestLeaseMs?: number;
-    /**
-     * Maximum time a duplicate idempotent create waits for completion or stale
-     * lease takeover before raising `ClientRequestPendingError`. Defaults to 5000 ms.
-     */
-    clientRequestWaitMs?: number;
-    /** Poll interval while waiting for an idempotent create outcome. Defaults to 200 ms. */
-    clientRequestPollMs?: number;
-    /** Test hook for deterministic waiting; production uses `setTimeout`. */
-    clientRequestDelay?: (ms: number) => Promise<void>;
-}
-interface MessageServiceModelNames {
-    active: string;
-    archive: string;
-    request: string;
-    user: string;
-}
-interface PaymentCompensationFailureEvent {
-    operation: 'expire';
-    sessionId: string;
-    error: unknown;
-    originalError: unknown;
-    clientRequestId?: string;
-    clientRequestOwnerId?: string;
-    templateCd?: string;
-}
-type HydratedModelSource = {
-    constructor: unknown;
-};
-type MessageModelRole = keyof MessageServiceModelNames;
-/**
- * The `templateCd` used for generic notifications created via
- * `createNotification`. These messages have no actions, so
- * `getActions` returns an empty list for them.
- */
-declare const GENERIC_NOTIFICATION_TEMPLATE_CD = "__generic-notification__";
+/** Model roles the service resolves on a Mongoose connection or resolver. */
+type MessageModelRole = 'active' | 'archive' | 'request' | 'user';
 declare class MessageNotFoundError extends Error {
     static [Symbol.hasInstance](value: unknown): boolean;
     constructor(messageId: string);
@@ -1472,12 +1623,28 @@ declare class InvalidPaginationValueError extends Error {
     static [Symbol.hasInstance](value: unknown): boolean;
     constructor(message: string);
 }
+declare class InvalidMessageServiceOptionError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(message: string);
+}
 declare class ClientRequestPendingError extends Error {
     static [Symbol.hasInstance](value: unknown): boolean;
     constructor(clientRequestId: string);
 }
 declare class ClientRequestFailedError extends Error {
     static [Symbol.hasInstance](value: unknown): boolean;
+    /**
+     * Scoped request id for this recorded failure. Safe to expose: it is the
+     * caller-supplied id within the caller's own owner/template scope.
+     */
+    clientRequestId: string;
+    /**
+     * Recorded terminal-failure diagnostic (the `failureMessage` persisted on
+     * the request record). Retained for internal observers/direct-service
+     * callers; never serialized into HTTP responses. See `route-factory`
+     * `mapServiceError`, which returns a stable public message without it.
+     */
+    failureReason: string | null;
     constructor(clientRequestId: string, reason?: string | null);
 }
 declare class ClientRequestInconsistentStateError extends Error {
@@ -1504,6 +1671,156 @@ declare class PaymentSessionCompensationError extends Error {
     hookError?: unknown;
     constructor(sessionId: string, operation: 'expire', compensationError: unknown, originalError: unknown, hookError?: unknown);
 }
+/**
+ * One failed `expireSession` (or compensation-hook) attempt within a batch.
+ */
+interface PaymentSessionCompensationFailure {
+    sessionId: string;
+    compensationError: unknown;
+    hookError?: unknown;
+}
+/**
+ * Thrown when compensating a multi-session batch leaves one or more
+ * uncommitted sessions unexpired.
+ *
+ * Extends `PaymentSessionCompensationError` so existing single-session
+ * `instanceof` checks keep working. `sessionId`/`compensationError`/
+ * `hookError` mirror the first failure for backwards compatibility; the full
+ * per-session list lives in `failures` and `originalError` is the failure
+ * that triggered compensation. Every known session is attempted even when an
+ * earlier cleanup fails, and the hook is invoked once per failed session.
+ */
+declare class PaymentSessionCompensationAggregateError extends PaymentSessionCompensationError {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    failures: PaymentSessionCompensationFailure[];
+    constructor(failures: PaymentSessionCompensationFailure[], originalError: unknown);
+}
+
+interface MessageServiceOptions {
+    getModel?: (name: string) => mongoose.Model<unknown>;
+    connection?: mongoose.Connection;
+    modelNames?: Partial<MessageServiceModelNames>;
+    paymentProvider?: PaymentProvider | null;
+    /**
+     * Called when the service cannot expire an external payment session that was
+     * created for a message batch that did not commit.
+     */
+    onPaymentCompensationFailure?: (event: PaymentCompensationFailureEvent) => void | Promise<void>;
+    /**
+     * Observes `endSession()` rejection for service-owned batch/action transactions.
+     * Confirmed commits and primary transaction errors are preserved even if this
+     * observer throws/rejects. Awaited best-effort diagnostics; keep it bounded.
+     * Configure `buildMessageSchema` separately for direct document `archive()`.
+     */
+    onTransactionCleanupFailure?: MessageTransactionCleanupFailureObserver;
+    adminRoles?: string[];
+    registry?: TemplateRegistry;
+    /**
+     * Maximum number of messages returned by `listMessages` when no explicit
+     * limit is provided. Defaults to 50.
+     */
+    defaultListLimit?: number;
+    /**
+     * Hard upper bound for `listMessages` limit to prevent abuse. Defaults to 100.
+     */
+    maxListLimit?: number;
+    /**
+     * How long a pending idempotent create reservation lease remains live before
+     * another caller may atomically take it over. Defaults to 30000 ms.
+     *
+     * Must be a finite safe integer in `[1, 2147483647]` ms (positive lease).
+     * The upper bound is Node's maximum `setTimeout` delay (`2^31 - 1`); larger
+     * values would not fire on the intended cadence. Fractional, `NaN`,
+     * infinite, negative, zero, or overflowing values throw
+     * `InvalidMessageServiceOptionError` at construction.
+     */
+    clientRequestLeaseMs?: number;
+    /**
+     * Maximum time a duplicate idempotent create waits for completion or stale
+     * lease takeover before raising `ClientRequestPendingError`. Defaults to 5000 ms.
+     *
+     * Must be a finite safe integer in `[0, 2147483647]` ms (nonnegative wait).
+     * `0` is a supported immediate check: a duplicate that cannot acquire or
+     * replay on its first attempt raises `ClientRequestPendingError` without
+     * sleeping. The wait deadline bounds polling only — it never cancels a hung
+     * database/provider operation. Out-of-range values throw
+     * `InvalidMessageServiceOptionError` at construction.
+     */
+    clientRequestWaitMs?: number;
+    /**
+     * Poll interval while waiting for an idempotent create outcome. Defaults to 200 ms.
+     *
+     * Must be a finite safe integer in `[1, 2147483647]` ms (positive poll).
+     * Out-of-range values throw `InvalidMessageServiceOptionError` at construction.
+     */
+    clientRequestPollMs?: number;
+    /** Test hook for deterministic waiting; production uses `setTimeout`. */
+    clientRequestDelay?: (ms: number) => Promise<void>;
+    /**
+     * Test hook for deterministic time. Defaults to `Date.now`.
+     *
+     * The same clock drives the duplicate-wait deadline and the persisted
+     * `leaseExpiresAt` wall-clock timestamps (`new Date(now())`), so fake
+     * clocks stay coherent in tests. The stale-takeover filter compares
+     * `leaseExpiresAt` against this clock, not an independent `new Date()`.
+     * Production uses real wall-clock time.
+     */
+    clientRequestNow?: () => number;
+}
+interface MessageServiceModelNames {
+    active: string;
+    archive: string;
+    request: string;
+    user: string;
+}
+interface PaymentCompensationFailureEvent {
+    operation: 'expire';
+    sessionId: string;
+    error: unknown;
+    originalError: unknown;
+    clientRequestId?: string;
+    clientRequestOwnerId?: string;
+    templateCd?: string;
+}
+/**
+ * Maximum platform timer delay (`2^31 - 1` ms, ~24.8 days). Node's
+ * `setTimeout` clamps/overflows beyond this, so lease/wait/poll values above
+ * it are rejected at construction rather than silently misfiring.
+ */
+declare const MAX_MESSAGE_SERVICE_TIMEOUT_MS = 2147483647;
+type HydratedModelSource = {
+    constructor: unknown;
+};
+/**
+ * The `templateCd` used for generic notifications created via
+ * `createNotification`. These messages have no actions, so
+ * `getActions` returns an empty list for them.
+ */
+declare const GENERIC_NOTIFICATION_TEMPLATE_CD = "__generic-notification__";
+/**
+ * Shared principal-validation contract for user-facing service entry points
+ * and HTTP routes.
+ *
+ * A valid principal id is a non-empty string (after trimming) or a
+ * `mongoose.Types.ObjectId` instance. Missing, null, empty/whitespace-only,
+ * numeric, array, and plain-object ids are invalid. Valid string ids keep
+ * their string type (trimmed); valid ObjectId instances are preserved as
+ * ObjectId by callers and normalized to their hex string only where a string
+ * scope/query key is required.
+ *
+ * `findMessage`/`findMessageOrThrow` and `createNotification` are trusted
+ * host-level operations and intentionally do not take a principal; they are
+ * not part of this contract.
+ */
+declare function isValidMessageUserId(id: unknown): id is string | mongoose.Types.ObjectId;
+/**
+ * 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
+ * left untouched so ObjectId-backed schemas keep their native type.
+ */
+declare function requireMessageUserId(user: unknown): string;
 /**
  * Core message service for creating messages, getting actions, and handling actions.
  *
@@ -1518,6 +1835,7 @@ declare class MessageService {
     private expirePaymentSession?;
     private refundPaymentSession?;
     private onPaymentCompensationFailure?;
+    private onTransactionCleanupFailure?;
     private adminRoles;
     private registry;
     private defaultListLimit;
@@ -1526,20 +1844,51 @@ declare class MessageService {
     private clientRequestWaitMs;
     private clientRequestPollMs;
     private clientRequestDelay;
+    private clientRequestNow;
     private actionLeaseMs;
     constructor(options: MessageServiceOptions);
     /**
      * 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`).
      */
     findMessage(messageId: string, options?: {
         populate?: string | string[] | mongoose.PopulateOptions | mongoose.PopulateOptions[];
         select?: string | Record<string, 0 | 1 | boolean>;
     }): Promise<IMessage | IMessageArchive | null>;
+    /**
+     * 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.
+     */
     findMessageOrThrow(messageId: string, options?: {
         populate?: string | string[] | mongoose.PopulateOptions | mongoose.PopulateOptions[];
         select?: string | Record<string, 0 | 1 | boolean>;
     }): Promise<IMessage | IMessageArchive>;
+    /**
+     * 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.
+     */
     createMessage(params: {
         templateCd: string;
         user: MessageUser;
@@ -1555,9 +1904,16 @@ declare class MessageService {
          * characters. Replays are scoped to the requester identity and template.
          */
         clientRequestId?: unknown;
-    }): Promise<IMessage[]>;
+    }): Promise<Array<IMessage | IMessageArchive>>;
     private createMessageWithReservation;
     private createPreparedMessageBatch;
+    /**
+     * 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.
+     */
     createNotification(params: {
         fromUser?: UserId | null;
         toUser?: UserId | null;
@@ -1578,12 +1934,17 @@ declare class MessageService {
      * 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: MessageUser): Record<string, unknown>;
     /**
      * 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 }`.
      */
     listMessages(params: {
         user: MessageUser;
@@ -1594,18 +1955,57 @@ 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.
      */
     countMessages(user: MessageUser): Promise<number>;
-    getActions(messageId: string, usertype: Usertype, options?: {
+    /**
+     * 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`.
+     */
+    getActions(messageId: string, usertype: Usertype, options: {
+        /** Authenticated caller; required. Validated before any effect. */
+        user: MessageUser;
         permissions?: Record<string, boolean>;
+        /** @deprecated Ignored. The requested id is always re-read from storage; omit this option. */
         message?: IMessage | IMessageArchive;
-        user?: MessageUser;
         isAdmin?: boolean;
+        /** Presentation population for eligible active conditions, after relationship authorization. */
         populate?: string | string[] | mongoose.PopulateOptions | mongoose.PopulateOptions[];
     }): Promise<{
         uiTemplate: UiTemplate;
         actions: InterpolatedAction[];
     } | null>;
+    /**
+     * 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).
+     */
     handleAction(templateCd: string, actionCd: string, data: {
         message: IMessage | IMessageArchive;
         user: MessageUser;
@@ -1624,17 +2024,61 @@ declare class MessageService {
     private compensatePaymentSession;
     private buildActionContext;
     private claimAction;
+    /**
+     * 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.
+     */
+    private authorizeArchivedOutcome;
+    /** Call only with an authoritative, unpopulated archive read. */
+    private throwArchivedOutcome;
+    /**
+     * 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.
+     */
+    private authorizeClaimedAction;
+    private releaseDeniedActionClaim;
     private markActionRetryable;
     private archiveClaimedMessage;
     private markActionNotificationState;
     private runSenderNotification;
     private normalizeClientRequestId;
     private validatePositiveIntegerOption;
+    private validateDurationOption;
     private normalizeListLimit;
     private normalizeListSkip;
     private buildClientRequestScope;
     private requireUserId;
     private findByClientRequestScope;
+    private findArchivedByClientRequestScope;
+    /**
+     * 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.
+     */
+    private mergeReplayBatch;
+    private buildCompletedReplay;
     private findCompletedClientRequestReplay;
     private acquireClientRequestStart;
     private tryAcquireClientRequestLease;
@@ -1642,57 +2086,198 @@ declare class MessageService {
     private tryTakeOverStaleClientRequestReservation;
     private findClientRequestReservation;
     private failClientRequestReservation;
-    private isDuplicateKeyError;
-    private isTransactionSupportError;
     private delay;
     private isArchivedMessage;
     private applyPopulate;
     private findByIdWithOptions;
 }
 
-interface MessageRoutesOptions {
-    /** Mongoose model getter */
-    getModel: (name: string) => mongoose.Model<unknown>;
-    /** Payment provider (optional — enables payment session handling) */
-    paymentProvider?: PaymentProvider | null;
-    /** Optional hook called when expiring an uncommitted payment session fails. */
-    onPaymentCompensationFailure?: MessageServiceOptions['onPaymentCompensationFailure'];
-    /** Admin roles that receive messages when no toUser/toRoles specified */
-    adminRoles?: string[];
-    /**
-     * Custom template registry. Use this to isolate templates per app or test
-     * instead of relying on the global `defaultRegistry`. Pass the same registry
-     * instance to `MessageService` if you also construct one directly.
-     */
-    registry?: TemplateRegistry;
+/** A populated party exposes only its identity and optional presentation fields. */
+interface PublicMessageParty {
+    _id: string;
+    displayName?: string;
+    email?: string;
+}
+/**
+ * Allowlisted HTTP message representation, shared by create/replay and host lists.
+ * IDs are strings and dates are ISO strings. Archive-only fields are absent on
+ * active messages. Payload/display remain host-controlled business data.
+ */
+interface PublicMessageDto {
+    _id: string;
+    templateCd: string;
+    type: MessageType;
+    fromUser: string | PublicMessageParty | null;
+    toUser: string | PublicMessageParty | null;
+    toRoles: string[];
+    senderContent: IMessageContent;
+    receiverContent: IMessageContent;
+    documents: string[];
+    /** Business payment session reference, intentionally available to clients. */
+    paymentSession: string | null;
+    paymentCd: string;
+    payload: Record<string, unknown>;
+    display: Record<string, unknown>;
+    actionState: ActionLifecycleState;
+    actionCd: string | null;
+    /** Stable business deduplication ID, not the internal worker ownership token. */
+    actionAttemptId: string | null;
+    createdAt: string;
+    updatedAt: string;
+    archivedBy?: string | null;
+    archivedAt?: string;
+    actionNotificationState?: ActionNotificationState;
+}
+/**
+ * Structural input for hydrated or plain stored messages, including populated
+ * references. Unknown reference values are inspected only for IDs/presentation;
+ * missing or unsupported parties become null, never arbitrary serialized objects.
+ */
+type PublicMessageSource = Pick<IBaseMessage, 'templateCd' | 'type' | 'toRoles' | 'senderContent' | 'receiverContent' | 'paymentSession' | 'paymentCd' | 'payload' | 'display' | 'actionState' | 'actionCd' | 'actionAttemptId' | 'createdAt' | 'updatedAt'> & {
+    _id: unknown;
+    fromUser: unknown;
+    toUser: unknown;
+    documents: readonly unknown[];
+    archivedBy?: unknown;
+    archivedAt?: Date;
+    actionNotificationState?: ActionNotificationState;
+};
+/**
+ * Serialize an already-authorized message without mutating its hydrated record.
+ * Explicitly excludes diagnostics, owner tokens, claim/lease/request bookkeeping,
+ * schema extensions and arbitrary populated-user fields. Does not authorize or
+ * sanitize host payload/display/content or action handler results. Only populate
+ * email/displayName when they are appropriate for the audience.
+ *
+ * @example
+ * const data = (await service.listMessages({ user })).map(serializePublicMessage);
+ */
+declare function serializePublicMessage(message: PublicMessageSource): PublicMessageDto;
+
+/**
+ * Route-only behavior options shared by both composition paths.
+ *
+ * These never configure the underlying `MessageService`: auth middleware,
+ * request extractors, and the admin read-only permission key. They apply
+ * identically whether routes construct a service or reuse an injected one.
+ */
+interface MessageRoutesBehaviorOptions {
     /** Custom auth middleware applied to all routes */
     authMiddleware?: ((req: Request, res: Response, next: NextFunction) => void)[];
     /**
      * Extract user from request (default: req._user || req.user). All routes
-     * require this extractor to return a user with a non-empty `_id` before any
-     * service, template, payment, model, or action side effect runs.
+     * 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.
+     * Shares the service's principal-validation contract.
      */
     getUser?: (req: Request) => MessageUser | undefined;
-    /** Extract permissions from request (default: req._permissions || {}) */
+    /**
+     * Extract permissions from request (default: req._permissions || {}).
+     * Permission grants throughout the package (UI filtering, action
+     * execution, admin read-only) require an own property strictly equal to
+     * `true`; custom extractors must return plain own-boolean maps. Inherited
+     * properties and truthy non-booleans are denied.
+     */
     getPermissions?: (req: Request) => Record<string, boolean>;
     /** Extract identity from request (default: req._identity || {}) */
     getIdentity?: (req: Request) => Record<string, unknown>;
     /**
-     * Permission key that, when truthy, makes `getActions` return an empty
-     * action list (read-only view). Defaults to `'is.admin'`.
+     * Permission key that, when granted as an own boolean `true`, makes
+     * `getActions` return an empty action list (read-only view). Defaults to
+     * `'is.admin'`. Uses the same explicit-grant predicate as UI filtering and
+     * action execution, so inheritance (e.g. `constructor`) or truthy
+     * non-booleans cannot enable admin read-only mode.
      */
     adminPermissionKey?: string;
 }
+/**
+ * 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
+ * to `new MessageService(...)` so the route service never drifts behind the
+ * direct-service configuration surface.
+ */
+interface MessageRoutesConstructionOptions extends MessageRoutesBehaviorOptions, MessageServiceOptions {
+    /**
+     * Must be absent on this path. Supplying `service` together with any
+     * service construction option is a conflict (see
+     * `MessageRoutesInjectionOptions`); the factory throws
+     * `InvalidMessageServiceOptionError` instead of silently ignoring options.
+     */
+    service?: undefined;
+    /** Mongoose model getter (required on this path for backwards compatibility). */
+    getModel: NonNullable<MessageServiceOptions['getModel']>;
+}
+/**
+ * Service-injection path: routes reuse the exact supplied configured
+ * service (custom `modelNames`, `connection`, timing policies, providers,
+ * and registry included). No second service or global registry is created.
+ * Every service construction option is typed `never` here and rejected at
+ * runtime; route-only behavior options remain allowed.
+ */
+interface MessageRoutesInjectionOptions extends MessageRoutesBehaviorOptions {
+    /** Existing configured service reused verbatim (`returned.service === supplied`). */
+    service: MessageService;
+    getModel?: never;
+    connection?: never;
+    modelNames?: never;
+    paymentProvider?: never;
+    onPaymentCompensationFailure?: never;
+    onTransactionCleanupFailure?: never;
+    adminRoles?: never;
+    registry?: never;
+    defaultListLimit?: never;
+    maxListLimit?: never;
+    clientRequestLeaseMs?: never;
+    clientRequestWaitMs?: never;
+    clientRequestPollMs?: never;
+    clientRequestDelay?: never;
+    clientRequestNow?: never;
+}
+/**
+ * Supported route composition options: either construct a service from
+ * service options or reuse an existing service — never both.
+ *
+ * - Construction: `createMessageRoutes({ getModel, registry, ... })`.
+ * - Injection: `createMessageRoutes({ service, getUser, ... })`.
+ *
+ * Combining `service` with any service construction option throws
+ * `InvalidMessageServiceOptionError` at runtime (and fails strict type
+ * checking via the `never` fields on the injection branch) rather than
+ * silently ignoring the conflicting options.
+ */
+type MessageRoutesOptions = MessageRoutesConstructionOptions | MessageRoutesInjectionOptions;
 /**
  * Create a JsonRouter with the message template routes.
  * Mount via `router.original` and apply your own auth/permission middleware.
  *
+ * Composition (MSGF-11):
+ * - Convenience construction: `createMessageRoutes({ getModel, registry,
+ *   clientRequestWaitMs, ... })` builds and owns a `MessageService` from the
+ *   full service option set (no subsets).
+ * - Service injection: `createMessageRoutes({ service })` reuses the exact
+ *   supplied configured service — custom `modelNames`, `connection`, timing
+ *   policies, providers, and registry included — without creating a second
+ *   service or touching the global registry. Route-only behavior options
+ *   (`authMiddleware`, `getUser`, `getPermissions`, `getIdentity`,
+ *   `adminPermissionKey`) still apply on both paths.
+ *
+ * Combining `service` with any service construction option throws
+ * `InvalidMessageServiceOptionError` instead of silently ignoring conflicts.
+ * No per-method service callbacks are accepted; routes call the service API
+ * directly so authentication/validation/error mapping stay identical on both
+ * paths.
+ *
  * Routes:
- *   POST /new/:templateCd        — create message from template
+ *   POST /new/:templateCd        — create/replay as PublicMessageDto[]
  *   GET  /:id/actions/:usertype  — get available actions for a message
  *   POST /:id/action/:actionCd   — execute an action (POST)
  *
- * All routes require a resolved user with a non-empty `_id`. Route parameters
+ * All routes require a resolved user with a valid `_id` (non-empty string
+ * or ObjectId; numbers, arrays, and plain objects are rejected with 401).
+ * Route parameters
  * are validated before service/model/template lookup, and mutating actions are
  * intentionally POST-only.
  */
@@ -1701,4 +2286,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, InvalidMessageUserError, InvalidPaginationValueError, MESSAGE_ARCHIVE_MODEL_NAME, MESSAGE_MODEL_NAME, MESSAGE_REQUEST_MODEL_NAME, type MessageAction, MessageArchiveSchema, MessageArchivedError, MessageContentSchema, MessageModelResolutionError, MessageNotFoundError, MessageRequestSchema, type MessageRoutesOptions, MessageSchema, type MessageSchemaConfig, MessageService, type MessageServiceModelNames, type MessageServiceOptions, type MessageTemplate, MessageTransactionRequiredError, type MessageType, type MessageUser, NoopEmailProvider, NoopPaymentProvider, type PaymentCompensationFailureEvent, type PaymentProvider, PaymentSessionCompensationError, type PrepareContext, type PrepareResult, type SenderNotificationContent, TemplateNotFoundError, TemplateRegistry, TemplateRegistryValidationError, type UiTemplate, type UserId, type Usertype, buildMessageArchiveSchema, buildMessageRequestSchema, buildMessageSchema, createMessageRoutes, defaultRegistry, filterActions, includesAction, interpolateTemplate, isActionAllowed };
+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 };