@open-mercato/core 0.7.0 → 0.7.1-develop.7103.1.41ff100d93

package/src/modules/messages/api/openapi.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 import {
   attachmentIdsPayloadSchema,
+  composeMessageRequestSchema,
   composeMessageSchema,
   executeActionSchema,
   forwardMessageSchema,
@@ -50,11 +51,19 @@ export const messageListItemSchema = z.object({
   threadId: z.string().uuid().nullable().optional(),
 })
 
+export const enrichmentMetaSchema = z.object({
+  enrichedBy: z.array(z.string()),
+  enricherErrors: z.array(z.string()).optional(),
+})
+
 export const messageThreadItemSchema = z.object({
   id: z.string().uuid(),
   senderUserId: z.string().uuid(),
   senderName: z.string().nullable().optional(),
   senderEmail: z.string().nullable().optional(),
+  externalName: z.string().nullable().optional(),
+  externalEmail: z.string().nullable().optional(),
+  sourceEntityType: z.string().nullable().optional(),
   body: z.string(),
   bodyFormat: z.enum(['text', 'markdown']).optional(),
   sentAt: z.string().nullable().optional(),
@@ -126,7 +135,17 @@ export const messageDetailResponseSchema = z.object({
   isRead: z.boolean(),
   conversationArchived: z.boolean(),
   conversationAllUnread: z.boolean(),
+  _channel: z.record(z.string(), z.unknown()).nullable().optional(),
+  _channelPayload: z.record(z.string(), z.unknown()).nullable().optional(),
+  _channelContact: z.record(z.string(), z.unknown()).nullable().optional(),
+  _reactions: z.array(z.record(z.string(), z.unknown())).optional(),
+  _meta: enrichmentMetaSchema.optional(),
 })
+  // The detail route runs response enrichers for `messages.message`, so any
+  // module registering one may contribute further `_`-prefixed keys. Without
+  // this the generator emits `additionalProperties: false` and the published
+  // spec forbids the very fields the route returns.
+  .passthrough()
 
 export const messageTokenDetailResponseSchema = z.object({
   id: z.string().uuid(),
@@ -265,6 +284,7 @@ export {
   messageObjectSchema,
   messageRecipientSchema,
   composeMessageSchema,
+  composeMessageRequestSchema,
   listMessagesSchema,
   forwardMessageSchema,
   replyMessageSchema,

package/src/modules/messages/api/route.ts

@@ -17,6 +17,11 @@ import { lookupHashCandidates } from '@open-mercato/shared/lib/encryption/aes'
 import { User } from '../../auth/data/entities'
 import { Message, MessageObject } from '../data/entities'
 import { composeMessageSchema, listMessagesSchema, type ListMessagesInput } from '../data/validators'
+import {
+  composeRequiresChannelTypeResolution,
+  composeSourceHintSchema,
+  resolveComposeSourceChannelType,
+} from '../lib/composeSourceChannelType'
 import { MESSAGE_ATTACHMENT_ENTITY_ID } from '../lib/constants'
 import { getMessageType } from '../lib/message-types-registry'
 import { validateMessageObjectsForType } from '../lib/object-validation'
@@ -27,7 +32,7 @@ import { resolveUserFeatures, runMessageMutationGuardAfterSuccess, runMessageMut
 import { findMessageIdsBySearchTokens } from '../lib/searchLookup'
 import { MessageCommandExecuteResult } from '../commands/shared'
 import {
-  composeMessageSchema as composeSchema,
+  composeMessageRequestSchema as composeSchema,
   composeResponseSchema,
   listMessagesSchema as listSchema,
   messageListItemSchema,
@@ -445,7 +450,31 @@ export async function POST(req: Request) {
   const { ctx, scope } = await resolveMessageContext(req)
   const commandBus = ctx.container.resolve('commandBus') as CommandBus
   const body = await req.json().catch(() => ({}))
-  const input = composeMessageSchema.parse(body)
+
+  // #4975: whether `externalEmail` is required depends on the channel this
+  // message originates from, so the channel type has to be established BEFORE
+  // validation. It is resolved server-side from the referenced conversation or
+  // parent message and any client-sent `sourceChannelType` is dropped —
+  // otherwise a caller could waive the requirement by asserting its own type.
+  // An unresolvable source stays `undefined`, which the validator fails closed on.
+  // Only the "public, non-draft, no address" branch of the validator reads the
+  // answer, so every other compose skips the lookup instead of discarding it.
+  const sourceHint = composeRequiresChannelTypeResolution(body)
+    ? composeSourceHintSchema.safeParse(body)
+    : null
+  const sourceChannelType = sourceHint?.success
+    ? await resolveComposeSourceChannelType(
+        ctx.container,
+        { tenantId: scope.tenantId, organizationId: scope.organizationId ?? null },
+        sourceHint.data,
+      )
+    : undefined
+  const { sourceChannelType: _clientSuppliedChannelType, ...clientBody } =
+    (body ?? {}) as Record<string, unknown>
+  const input = composeMessageSchema.parse({
+    ...clientBody,
+    ...(sourceChannelType ? { sourceChannelType } : {}),
+  })
 
   const isPublicVisibility = input.visibility === 'public'
   const sendViaEmail = isPublicVisibility ? true : input.sendViaEmail

package/src/modules/messages/components/MessagesInboxPageClient.tsx

@@ -24,6 +24,7 @@ import { useMessagesInboxBulkActions, type MessageFolder } from './useMessagesIn
 import {
   buildMessagesInboxFilters,
   buildMessagesListParams,
+  buildSenderOptionsFromMessages,
   type SenderOption,
 } from './inboxFilters'
 import { createLogger } from '@open-mercato/shared/lib/logger'
@@ -38,6 +39,9 @@ type MessageListItem = {
   senderUserId: string
   senderName?: string | null
   senderEmail?: string | null
+  externalName?: string | null
+  externalEmail?: string | null
+  sourceEntityType?: string | null
   priority: string
   status: string
   hasObjects: boolean
@@ -58,6 +62,7 @@ type MessageListResponse = {
   page?: number
   pageSize?: number
   totalPages?: number
+  totalIsCapped?: boolean
 }
 
 type MessageTypeItem = {
@@ -138,6 +143,7 @@ export function MessagesInboxPageClient() {
         page: Number(call.result?.page ?? page),
         pageSize: Number(call.result?.pageSize ?? pageSize),
         totalPages: Number(call.result?.totalPages ?? 0),
+        totalIsCapped: call.result?.totalIsCapped === true,
       }
     },
   })
@@ -236,22 +242,7 @@ export function MessagesInboxPageClient() {
 
   React.useEffect(() => {
     const items = listQuery.data?.items ?? []
-    const next = items.flatMap((item): SenderOption[] => {
-      if (typeof item.senderUserId !== 'string' || item.senderUserId.trim().length === 0) return []
-      const name = typeof item.senderName === 'string' && item.senderName.trim().length > 0
-        ? item.senderName.trim()
-        : null
-      const email = typeof item.senderEmail === 'string' && item.senderEmail.trim().length > 0
-        ? item.senderEmail.trim()
-        : null
-      const label = name ?? email ?? item.senderUserId
-      return [{
-        value: item.senderUserId,
-        label,
-        description: email && email !== label ? email : null,
-      }]
-    })
-    mergeSenderOptions(next)
+    mergeSenderOptions(buildSenderOptionsFromMessages(items))
   }, [listQuery.data?.items, mergeSenderOptions])
 
   React.useEffect(() => {
@@ -361,6 +352,7 @@ export function MessagesInboxPageClient() {
 
   const rows = listQuery.data?.items ?? []
   const total = listQuery.data?.total ?? 0
+  const totalIsCapped = listQuery.data?.totalIsCapped === true
   const totalPages = listQuery.data?.totalPages ?? 0
 
   return (
@@ -398,6 +390,7 @@ export function MessagesInboxPageClient() {
           pageSize,
           total,
           totalPages,
+          totalIsCapped,
           onPageChange: setPage,
         }}
         actions={

package/src/modules/messages/components/inboxFilters.ts

@@ -8,6 +8,42 @@ export type SenderOption = {
   description?: string | null
 }
 
+type SenderOptionSource = {
+  senderUserId?: string | null
+  senderName?: string | null
+  senderEmail?: string | null
+}
+
+/**
+ * Sender-filter options derived from the rows currently in the list.
+ *
+ * The filter narrows by `senderUserId`, so a row only yields an honest option
+ * when it also carries the platform identity behind that id. Ingested external
+ * mail does not: every such message in a tenant is composed under one
+ * system-user id, so labelling that id with one external sender's name would
+ * collapse every external sender into a single option that quietly returns all
+ * of their mail. Those rows are skipped, and the directory-loaded options —
+ * which are real platform users — stand alone.
+ */
+export function buildSenderOptionsFromMessages(items: SenderOptionSource[]): SenderOption[] {
+  return items.flatMap((item): SenderOption[] => {
+    if (typeof item.senderUserId !== 'string' || item.senderUserId.trim().length === 0) return []
+    const name = typeof item.senderName === 'string' && item.senderName.trim().length > 0
+      ? item.senderName.trim()
+      : null
+    const email = typeof item.senderEmail === 'string' && item.senderEmail.trim().length > 0
+      ? item.senderEmail.trim()
+      : null
+    const label = name ?? email
+    if (!label) return []
+    return [{
+      value: item.senderUserId,
+      label,
+      description: email && email !== label ? email : null,
+    }]
+  })
+}
+
 export type MessagesInboxFilterContext = {
   t: Translator
   typeOptions: { value: string; label: string }[]

package/src/modules/messages/components/message-detail/hooks/useMessageDetailsConversation.ts

@@ -4,12 +4,16 @@ import * as React from 'react'
 import type { TranslateFn } from '@open-mercato/shared/lib/i18n/context'
 import type { MessageListItemProps } from '@open-mercato/shared/modules/messages/types'
 import type { MessageDetail } from '../types'
+import { getMessageParticipantLabel } from '../../messageListLabels'
 
 export type ConversationItem = {
   id: string
   senderUserId: string
   senderName?: string | null
   senderEmail?: string | null
+  externalName?: string | null
+  externalEmail?: string | null
+  sourceEntityType?: string | null
   body: string
   bodyFormat?: 'text' | 'markdown'
   sentAt?: string | null
@@ -33,6 +37,9 @@ export function useMessageDetailsConversation({
         senderUserId: detail.senderUserId,
         senderName: detail.senderName,
         senderEmail: detail.senderEmail,
+        externalName: detail.externalName,
+        externalEmail: detail.externalEmail,
+        sourceEntityType: detail.sourceEntityType,
         body: detail.body,
         bodyFormat: detail.bodyFormat,
         sentAt: detail.sentAt,
@@ -46,6 +53,9 @@ export function useMessageDetailsConversation({
         senderUserId: item.senderUserId,
         senderName: item.senderName,
         senderEmail: item.senderEmail,
+        externalName: item.externalName,
+        externalEmail: item.externalEmail,
+        sourceEntityType: item.sourceEntityType,
         body: item.body,
         bodyFormat: item.bodyFormat,
         sentAt: item.sentAt,
@@ -58,6 +68,9 @@ export function useMessageDetailsConversation({
         senderUserId: detail.senderUserId,
         senderName: detail.senderName,
         senderEmail: detail.senderEmail,
+        externalName: detail.externalName,
+        externalEmail: detail.externalEmail,
+        sourceEntityType: detail.sourceEntityType,
         body: detail.body,
         bodyFormat: detail.bodyFormat,
         sentAt: detail.sentAt,
@@ -114,7 +127,7 @@ export function useMessageDetailsConversation({
     bodyFormat: item.bodyFormat ?? 'text',
     priority: 'normal',
     sentAt: item.sentAt ? new Date(item.sentAt) : null,
-    senderName: item.senderName || item.senderEmail || item.senderUserId,
+    senderName: getMessageParticipantLabel(item),
     hasObjects: (item.objects ?? []).length > 0,
     objectCount: (item.objects ?? []).length,
     hasAttachments: false,

package/src/modules/messages/components/message-detail/panels/MessageHeader.tsx

@@ -18,6 +18,7 @@ import {
 } from 'lucide-react'
 import type { MessageDetail } from '../types'
 import { formatDateTime } from '../utils'
+import { getMessageParticipantLabel } from '../../messageListLabels'
 
 type MessageHeaderProps = {
   detail: MessageDetail
@@ -40,6 +41,7 @@ export function MessageHeader(props: MessageHeaderProps) {
   const t = useT()
   const showSubject = props.showSubject !== false
   const canReply = !props.detail.isDraft && props.detail.typeDefinition.allowReply
+  const senderLabel = getMessageParticipantLabel(props.detail)
   const actionItems = React.useMemo(() => {
     const items: ActionItem[] = []
 
@@ -121,7 +123,7 @@ export function MessageHeader(props: MessageHeaderProps) {
         <FormHeader
           mode="detail"
           title={showSubject ? props.detail.subject : undefined}
-          subtitle={`${t('messages.detail.from', 'From')}: ${props.detail.senderName || props.detail.senderEmail || props.detail.senderUserId}`}
+          subtitle={`${t('messages.detail.from', 'From')}: ${senderLabel}`}
           statusBadge={<p className="text-xs text-muted-foreground">{formatDateTime(props.detail.sentAt)}</p>}
           utilityActions={canReply ? (
             <IconButton

package/src/modules/messages/components/message-detail/panels/thread-panel.tsx

@@ -6,6 +6,7 @@ import { getMessageUiComponentRegistry } from '../../utils/typeUiRegistry'
 import { getMessageObjectType } from '../../../lib/message-objects-registry'
 import type { MessageDetail, MessageDetailObject } from '../types'
 import { formatDateTime } from '../utils'
+import { getMessageParticipantLabel } from '../../messageListLabels'
 
 export function MessageDetailThreadSection({ detail }: { detail: MessageDetail }) {
   const t = useT()
@@ -20,7 +21,7 @@ export function MessageDetailThreadSection({ detail }: { detail: MessageDetail }
         {(detail.thread ?? []).map((threadItem) => (
           <article key={threadItem.id} className="rounded border p-3">
             <p className="text-xs text-muted-foreground">
-              {(threadItem.senderName || threadItem.senderEmail || threadItem.senderUserId)} • {formatDateTime(threadItem.sentAt)}
+              {getMessageParticipantLabel(threadItem)} • {formatDateTime(threadItem.sentAt)}
             </p>
             <div className="mt-2 max-h-[60vh] overflow-y-auto pr-1">
               <MarkdownContent

package/src/modules/messages/components/message-detail/types.ts

@@ -94,6 +94,9 @@ export type MessageDetail = {
     senderUserId: string
     senderName?: string | null
     senderEmail?: string | null
+    externalName?: string | null
+    externalEmail?: string | null
+    sourceEntityType?: string | null
     body: string
     bodyFormat?: 'text' | 'markdown'
     sentAt?: string | null

package/src/modules/messages/components/messageListLabels.ts

@@ -2,9 +2,29 @@ import type { MessageFolder } from './useMessagesInboxBulkActions'
 
 type Translate = (key: string, fallback: string, params?: Record<string, string | number>) => string
 
+/**
+ * `Message.sourceEntityType` written by `communication_channels`'
+ * `ingest-inbound-message` command, and by nothing else — the outbound bridge
+ * treats it as the marker that a message arrived from outside the platform
+ * rather than being sent from it. It is the only reliable inbound
+ * discriminator: `type` is `channel.<provider>` on the outbound
+ * `send-as-user` path too, where `externalName` carries the recipient side.
+ */
+const INBOUND_EXTERNAL_SOURCE_ENTITY_TYPE = 'communication_channels.external_conversation'
+
 type MessageParticipantSource = {
   senderName?: string | null
   senderEmail?: string | null
+  /**
+   * The external counterparty on a message that crosses the platform boundary —
+   * the sender for an inbound email/chat ingested by `communication_channels`,
+   * the recipient for an outbound reply sent through `inbox_ops`. Which side it
+   * represents is decided by `sourceEntityType`, not by whether a platform
+   * sender happens to be present.
+   */
+  externalName?: string | null
+  externalEmail?: string | null
+  sourceEntityType?: string | null
   senderUserId: string
   recipientCount?: number | null
 }
@@ -14,6 +34,37 @@ function normalizeLabel(value: string | null | undefined): string | null {
   return normalized ? normalized : null
 }
 
+function isInboundExternalMessage(item: MessageParticipantSource): boolean {
+  return item.sourceEntityType === INBOUND_EXTERNAL_SOURCE_ENTITY_TYPE
+}
+
+/**
+ * Human-readable label for a message's author.
+ *
+ * An ingested inbound message is authored by the external counterparty, even
+ * though it is composed under a platform user id: that id is the
+ * `communication_channels` system user, or — once an operator assigns the
+ * conversation — the assigned agent, who resolves to a real name in the user
+ * directory and would otherwise be printed as the author of the customer's own
+ * email. So on the inbound side the external identity wins, and the platform
+ * identity is only the fallback. Everywhere else the platform sender is the
+ * author and the external identity describes the recipient, so the order is
+ * reversed. The raw user id remains the last resort in both directions.
+ *
+ * The single source of truth for every place the messages module prints a
+ * participant — the inbox list, the detail header and the conversation rows —
+ * so an ingested email renders as "Jane Doe" / "jane@example.com" rather than
+ * the `communication_channels` system user id or the agent handling it.
+ */
+export function getMessageParticipantLabel(item: MessageParticipantSource): string {
+  const platformIdentity = normalizeLabel(item.senderName) ?? normalizeLabel(item.senderEmail)
+  const externalIdentity = normalizeLabel(item.externalName) ?? normalizeLabel(item.externalEmail)
+  const preferred = isInboundExternalMessage(item) ? externalIdentity : platformIdentity
+  const fallback = isInboundExternalMessage(item) ? platformIdentity : externalIdentity
+
+  return preferred ?? fallback ?? item.senderUserId
+}
+
 export function getMessageListParticipantLabel(
   item: MessageParticipantSource,
   folder: MessageFolder,
@@ -23,7 +74,5 @@ export function getMessageListParticipantLabel(
     return t('messages.list.noRecipient', '(No recipient)')
   }
 
-  return normalizeLabel(item.senderName)
-    ?? normalizeLabel(item.senderEmail)
-    ?? item.senderUserId
+  return getMessageParticipantLabel(item)
 }

package/src/modules/messages/data/validators.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 import { parseBooleanFlag } from '@open-mercato/shared/lib/boolean'
 import { sanitizeRichTextHref } from '@open-mercato/shared/lib/html/sanitizeRichText'
+import { channelTypeRequiresExternalEmail } from '../lib/channel-sender-identity'
 
 function collectDuplicateRecipientIds(
   recipients: Array<{ userId: string }>,
@@ -99,13 +100,22 @@ export const messageActionDataSchema = z.object({
   expiresAt: z.string().datetime().optional(),
 })
 
-export const composeMessageSchema = z.object({
+const composeMessageBaseSchema = z.object({
   type: z.string().optional().default('default'),
   visibility: z.enum(['public', 'internal']).nullable().optional(),
   sourceEntityType: z.string().min(1).optional(),
   sourceEntityId: z.string().uuid().optional(),
   externalEmail: z.string().email().optional(),
   externalName: z.string().min(1).max(255).optional(),
+  /**
+   * Channel type the message originates from, when the caller knows it (#4975).
+   * Non-email channels (Discord, Slack, SMS…) have senders with no address, so
+   * `externalEmail` is not required for them. Resolved server-side — the HTTP
+   * route strips any client-sent value and derives it from the referenced
+   * conversation or parent message, so a caller cannot waive the requirement by
+   * asserting its own channel type.
+   */
+  sourceChannelType: z.string().min(1).max(64).optional(),
   recipients: z.array(messageRecipientSchema).max(100).optional().default([]),
   subject: z.string().max(500).optional().default(''),
   body: z.string().max(50000).optional().default(''),
@@ -118,7 +128,14 @@ export const composeMessageSchema = z.object({
   sendViaEmail: z.boolean().optional().default(false),
   parentMessageId: z.string().uuid().optional(),
   isDraft: z.boolean().optional().default(false),
-}).superRefine((value, ctx) => {
+})
+
+type ComposeMessageRefinementValue = Omit<
+  z.infer<typeof composeMessageBaseSchema>,
+  'sourceChannelType'
+> & { sourceChannelType?: string }
+
+function refineComposeMessage(value: ComposeMessageRefinementValue, ctx: z.RefinementCtx): void {
   const isDraft = value.isDraft ?? false
   const visibility = value.visibility ?? 'internal'
   const recipientCount = value.recipients.length
@@ -128,7 +145,10 @@ export const composeMessageSchema = z.object({
 
   if (!isDraft) {
     if (visibility === 'public') {
-      if (!hasExternalEmail) {
+      // #4975: an external correspondent is only guaranteed to have an address
+      // on an email-typed channel. `channelTypeRequiresExternalEmail` fails
+      // closed, so an unknown or absent channel type keeps the original rule.
+      if (!hasExternalEmail && channelTypeRequiresExternalEmail(value.sourceChannelType)) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           path: ['externalEmail'],
@@ -176,7 +196,26 @@ export const composeMessageSchema = z.object({
   }
 
   validateDefaultWithObjectsPayload(value, ctx)
-})
+}
+
+/**
+ * Full compose contract, including the server-resolved `sourceChannelType`.
+ * Used by the `messages.messages.compose` command and by the HTTP route AFTER
+ * it has resolved the channel type itself.
+ */
+export const composeMessageSchema = composeMessageBaseSchema.superRefine(refineComposeMessage)
+
+/**
+ * Client-facing compose contract — the same rules minus `sourceChannelType`,
+ * which is never accepted from a request body (#4975). Published in OpenAPI so
+ * the documented request shape matches what `POST /api/messages` actually reads:
+ * the route discards any client-sent channel type, resolves the real one from
+ * the referenced conversation or parent message, and only then validates against
+ * {@link composeMessageSchema}.
+ */
+export const composeMessageRequestSchema = composeMessageBaseSchema
+  .omit({ sourceChannelType: true })
+  .superRefine(refineComposeMessage)
 
 export const updateDraftSchema = z.object({
   type: z.string().optional(),

package/src/modules/messages/lib/channel-sender-identity.ts

@@ -0,0 +1,55 @@
+/**
+ * How the hub decides whether an external correspondent must be identified by an
+ * email address.
+ *
+ * Background (#4975): `composeMessageSchema` used to require `externalEmail` for
+ * every non-draft message with `visibility: 'public'` — which is every message
+ * from an external sender. That assumption holds only for email-typed channels.
+ * A Discord sender is a snowflake and has no address at all, so inbound Discord
+ * failed validation deterministically and the ingest job died in the queue while
+ * the channel still reported `Connected`.
+ *
+ * Variant A of the spec's § Open decision — hub sender-identity contract makes
+ * the requirement conditional on the originating channel type, and **fails
+ * closed**: only a channel type this list positively recognizes as non-email
+ * waives the requirement. An unrecognized, empty or absent channel type keeps
+ * the pre-existing behaviour, so no current caller changes and a typo'd or
+ * caller-asserted type cannot quietly switch a validation rule off.
+ *
+ * For these channels the sender identity is not lost — it is carried by
+ * `ExternalMessage.sender_identifier` and joined 1:1 to the platform message
+ * through `MessageChannelLink`.
+ *
+ * Adding a channel type here is additive and non-breaking: it only widens the
+ * set of inputs the hub accepts.
+ */
+const NON_EMAIL_SENDER_CHANNEL_TYPES = new Set([
+  'discord',
+  'slack',
+  'teams',
+  'telegram',
+  'signal',
+  'whatsapp',
+  'messenger',
+  'instagram',
+  'sms',
+  'push',
+])
+
+/**
+ * True when a message originating from `channelType` must carry an
+ * `externalEmail` to be composed with `visibility: 'public'`.
+ *
+ * Fail-closed by design — see the note above.
+ */
+export function channelTypeRequiresExternalEmail(channelType?: string | null): boolean {
+  if (typeof channelType !== 'string') return true
+  const normalized = channelType.trim().toLowerCase()
+  if (!normalized) return true
+  return !NON_EMAIL_SENDER_CHANNEL_TYPES.has(normalized)
+}
+
+/** The recognized non-email channel types, for tests and diagnostics. */
+export function listNonEmailSenderChannelTypes(): string[] {
+  return Array.from(NON_EMAIL_SENDER_CHANNEL_TYPES).sort((left, right) => left.localeCompare(right))
+}

package/src/modules/messages/lib/composeSourceChannelType.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod'
+
+/**
+ * Entity type a channel-backed conversation is exposed under on a message's
+ * `sourceEntityType`. Written by `communication_channels`' inbound ingest.
+ */
+const EXTERNAL_CONVERSATION_SOURCE_ENTITY_TYPE = 'communication_channels.external_conversation'
+
+/**
+ * The only parts of a compose body this resolution needs. Read defensively from
+ * the raw request body, before the body is validated, because the validation
+ * outcome itself depends on the answer (#4975).
+ */
+export const composeSourceHintSchema = z.object({
+  sourceEntityType: z.string().optional(),
+  sourceEntityId: z.string().uuid().optional(),
+  parentMessageId: z.string().uuid().optional(),
+})
+
+export type ComposeSourceHint = z.infer<typeof composeSourceHintSchema>
+
+/**
+ * Whether the compose validator can consult a resolved channel type at all.
+ *
+ * `sourceChannelType` is read in exactly one branch — a non-draft, public
+ * message that carries no address. Every internal reply, every draft and every
+ * public message that already supplies an address ignores it, so resolving it
+ * for them is a DI resolve plus a database round-trip whose answer is
+ * discarded. Mirrors `refineComposeMessage` and reads the raw body defensively,
+ * because this runs before validation. Skipping resolution yields `undefined`,
+ * which is already the fail-closed value.
+ */
+export function composeRequiresChannelTypeResolution(body: unknown): boolean {
+  if (!body || typeof body !== 'object') return false
+  const raw = body as Record<string, unknown>
+  if (raw.visibility !== 'public') return false
+  if (raw.isDraft === true) return false
+  const externalEmail = raw.externalEmail
+  return !(typeof externalEmail === 'string' && externalEmail.trim().length > 0)
+}
+
+type ResolveChannelTypeService = (
+  container: ContainerLike,
+  scope: { tenantId: string; organizationId: string | null },
+  reference: { externalConversationId?: string | null; messageId?: string | null },
+) => Promise<string | null>
+
+type ContainerLike = { resolve: <T = unknown>(name: string) => T }
+
+function tryResolveChannelTypeService(
+  container: ContainerLike,
+): ResolveChannelTypeService | undefined {
+  try {
+    return container.resolve<ResolveChannelTypeService>('communicationChannelsResolveChannelType')
+  } catch {
+    // `communication_channels` is optional: without it no message can originate
+    // from a channel, so "unknown" is both correct and fail-closed.
+    return undefined
+  }
+}
+
+/**
+ * Resolve the channel type a compose request originates from, server-side.
+ *
+ * Never derived from the request body's own `sourceChannelType` — that would let
+ * any caller waive the `externalEmail` requirement by asserting a channel type.
+ * It is looked up from the conversation the message is being composed on, or
+ * from the parent message it replies to.
+ *
+ * Returns `undefined` when nothing can be established, which the compose
+ * validator treats as "unknown" and therefore keeps the pre-#4975 rule.
+ */
+export async function resolveComposeSourceChannelType(
+  container: ContainerLike,
+  scope: { tenantId: string; organizationId: string | null },
+  hint: ComposeSourceHint,
+): Promise<string | undefined> {
+  const externalConversationId =
+    hint.sourceEntityType === EXTERNAL_CONVERSATION_SOURCE_ENTITY_TYPE
+      ? hint.sourceEntityId ?? null
+      : null
+  const messageId = hint.parentMessageId ?? null
+  if (!externalConversationId && !messageId) return undefined
+
+  const resolveChannelType = tryResolveChannelTypeService(container)
+  if (!resolveChannelType) return undefined
+
+  const channelType = await resolveChannelType(container, scope, {
+    externalConversationId,
+    messageId,
+  })
+  return channelType ?? undefined
+}
+
+export { EXTERNAL_CONVERSATION_SOURCE_ENTITY_TYPE }