@open-mercato/core 0.6.5-develop.4384.1.ce2ec6eaaa → 0.6.5-develop.4393.1.de282b5dfd

package/src/modules/communication_channels/lib/connect-channel.ts

@@ -0,0 +1,163 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { CommunicationChannel } from '../data/entities'
+import type { ChannelAdapter } from './adapter'
+import { isUniqueViolation } from './pg-errors'
+
+/**
+ * Default poll cadence (seconds) for a polling-only channel — one whose adapter
+ * declares `realtimePush: false`. Push-capable channels use `null` (push-driven,
+ * no fixed poll). Shared so push teardown restores the same cadence connect uses.
+ */
+export const POLLING_ONLY_DEFAULT_INTERVAL_SECONDS = 300
+
+/**
+ * Thrown by {@link createConnectedChannelRow} when the same mailbox
+ * (`externalIdentifier`) is already connected for this user via a DIFFERENT
+ * provider. Both channels would poll the same inbox, and the per-channel
+ * `(channel_id, external_message_id)` dedup cannot dedupe the same email across
+ * channels — so every message would be ingested (and threaded) twice.
+ */
+export class MailboxAlreadyConnectedError extends Error {
+  readonly externalIdentifier: string
+  readonly existingProviderKey: string
+  constructor(externalIdentifier: string, existingProviderKey: string) {
+    super(`Mailbox ${externalIdentifier} is already connected via ${existingProviderKey}`)
+    this.name = 'MailboxAlreadyConnectedError'
+    this.externalIdentifier = externalIdentifier
+    this.existingProviderKey = existingProviderKey
+  }
+}
+
+export interface CreateConnectedChannelRowArgs {
+  em: EntityManager
+  adapter: Pick<ChannelAdapter, 'channelType' | 'capabilities'>
+  providerKey: string
+  displayName: string
+  externalIdentifier: string | null
+  credentialsRefId: string | null
+  userId: string
+  scope: { tenantId: string; organizationId: string | null }
+  /**
+   * Explicit poll-interval override (seconds). When omitted, it is derived from
+   * the adapter's push capability (push-capable → null, polling-only → 300).
+   */
+  pollIntervalSeconds?: number | null
+}
+
+/**
+ * Create + persist the per-user `CommunicationChannel` row for a connect flow.
+ * Shared by the credential-connect command and the OAuth callback so both entry
+ * points use one channel-shape implementation instead of duplicating `em.create`.
+ *
+ * When credentials could not be persisted (`credentialsRefId === null`) the row
+ * is created in `requires_reauth` + `isActive=false` so workers don't poll a
+ * credential-less channel; the user reconnects to recover.
+ */
+export async function createConnectedChannelRow(
+  args: CreateConnectedChannelRowArgs,
+): Promise<CommunicationChannel> {
+  const { em, adapter, providerKey, displayName, externalIdentifier, credentialsRefId, userId, scope } = args
+  const credentialsAvailable = credentialsRefId !== null
+  const pollIntervalSeconds =
+    args.pollIntervalSeconds !== undefined
+      ? args.pollIntervalSeconds
+      : adapter.capabilities?.realtimePush === false
+        ? POLLING_ONLY_DEFAULT_INTERVAL_SECONDS
+        : null
+  const dscope = { tenantId: scope.tenantId, organizationId: scope.organizationId ?? null }
+
+  // Cross-provider duplicate guard: the same mailbox must not be connected via
+  // two providers for one user. Both channels would poll the same inbox, and the
+  // per-channel `(channel_id, external_message_id)` dedup cannot dedupe the same
+  // email across channels — so every message would be ingested (and threaded)
+  // twice. Reconnecting the SAME provider/mailbox is fine (healed below); this
+  // only blocks a DIFFERENT provider for an already-connected address.
+  if (externalIdentifier) {
+    const normalized = externalIdentifier.toLowerCase()
+    const userChannels = (await findWithDecryption(
+      em,
+      CommunicationChannel,
+      { tenantId: scope.tenantId, userId, deletedAt: null },
+      undefined,
+      dscope,
+    )) as CommunicationChannel[]
+    const conflict = userChannels.find(
+      (existing) =>
+        existing.providerKey !== providerKey &&
+        typeof existing.externalIdentifier === 'string' &&
+        existing.externalIdentifier.toLowerCase() === normalized,
+    )
+    if (conflict) {
+      throw new MailboxAlreadyConnectedError(externalIdentifier, conflict.providerKey)
+    }
+  }
+
+  const naturalKey = {
+    tenantId: scope.tenantId,
+    userId,
+    providerKey,
+    externalIdentifier,
+    deletedAt: null,
+  }
+
+  // Heal-on-reconnect: a channel for the same (tenant, user, provider, mailbox)
+  // already exists when the user re-runs OAuth / reconnects after a
+  // `requires_reauth`. Update it in place rather than inserting a duplicate row —
+  // a duplicate would stay `isActive` and keep polling + re-emitting reauth
+  // banners, and register a second competing push subscription. Only mailboxes
+  // with a known `externalIdentifier` participate (the unique index is partial).
+  const applyConnectionState = (target: CommunicationChannel): void => {
+    target.channelType = adapter.channelType
+    target.displayName = displayName
+    target.externalIdentifier = externalIdentifier ?? null
+    target.credentialsRef = credentialsRefId
+    target.capabilities = adapter.capabilities as unknown as Record<string, unknown>
+    target.isActive = credentialsAvailable
+    target.pollIntervalSeconds = pollIntervalSeconds
+    target.status = credentialsAvailable ? 'connected' : 'requires_reauth'
+    target.lastError = credentialsAvailable ? null : 'credentials_persist_failed'
+  }
+
+  if (externalIdentifier) {
+    const existing = await findOneWithDecryption(em, CommunicationChannel, naturalKey, undefined, dscope)
+    if (existing) {
+      applyConnectionState(existing)
+      await em.flush()
+      return existing
+    }
+  }
+
+  const channel = em.create(CommunicationChannel, {
+    providerKey,
+    channelType: adapter.channelType,
+    displayName,
+    externalIdentifier: externalIdentifier ?? null,
+    credentialsRef: credentialsRefId,
+    capabilities: adapter.capabilities as unknown as Record<string, unknown>,
+    isActive: credentialsAvailable,
+    userId,
+    isPrimary: false,
+    pollIntervalSeconds,
+    status: credentialsAvailable ? 'connected' : 'requires_reauth',
+    lastError: credentialsAvailable ? null : 'credentials_persist_failed',
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId ?? null,
+  })
+  em.persist(channel)
+  try {
+    await em.flush()
+    return channel
+  } catch (err) {
+    // Concurrent connect for the same mailbox won the race (partial unique index
+    // rejected ours). Re-select the winner on a clean fork and heal it so the
+    // caller still gets a single, connected channel.
+    if (!isUniqueViolation(err) || !externalIdentifier) throw err
+    const reEm = em.fork()
+    const winner = await findOneWithDecryption(reEm, CommunicationChannel, naturalKey, undefined, dscope)
+    if (!winner) throw err
+    applyConnectionState(winner)
+    await reEm.flush()
+    return winner
+  }
+}

package/src/modules/communication_channels/lib/contact-resolver.ts

@@ -0,0 +1,162 @@
+import type { AwilixContainer } from 'awilix'
+import { isTenantDataEncryptionEnabled } from '@open-mercato/shared/lib/encryption/toggles'
+import type { ChannelAdapter, ContactHint, TenantScope } from './adapter'
+
+/**
+ * Contact resolver — used by the inbound bridge to attach an external sender
+ * to a CRM person.
+ *
+ * Flow (SPEC-045d §8.1):
+ *   1. If the adapter implements `resolveContact?(...)`, call it to get a
+ *      provider-side ContactHint (display name, photo URL, possibly an email
+ *      lookup the adapter performed against its own user directory).
+ *   2. If the hint includes an email or phone, query the CRM (`customers:customer_entity`)
+ *      via the **QueryEngine** (NOT raw SQL — root AGENTS.md mandate). If a person
+ *      matches, populate `matchedPersonId` on the returned hint.
+ *   3. Return the merged hint, or `null` if neither the adapter nor the CRM
+ *      yields any identity information.
+ */
+
+export interface ContactResolverInput {
+  adapter: ChannelAdapter
+  senderIdentifier: string
+  senderDisplayName?: string
+  channelMetadata?: Record<string, unknown>
+  credentials: Record<string, unknown>
+  scope: TenantScope
+}
+
+export interface ResolveContactDeps {
+  container: { resolve: <T = unknown>(name: string) => T }
+}
+
+type QueryEngineLike = {
+  query: (
+    entityType: string,
+    options: {
+      tenantId: string
+      organizationId?: string | null
+      filter?: Record<string, unknown>
+      limit?: number
+      offset?: number
+    },
+  ) => Promise<Record<string, unknown>[]>
+}
+
+/**
+ * Resolve a CRM contact from an external sender identifier.
+ *
+ * Returns `null` when no identity could be derived. Callers MUST treat the
+ * return value as advisory (a hint, not an authoritative match) — see spec
+ * § 8 "Contact resolution false positive" risk.
+ */
+export async function resolveContact(
+  input: ContactResolverInput,
+  deps: ResolveContactDeps,
+): Promise<ContactHint | null> {
+  // Step 1 — adapter resolution (optional)
+  const adapterHint: ContactHint | null = await runAdapterResolve(input)
+  if (!adapterHint && !input.senderIdentifier) return null
+
+  // Step 2 — CRM lookup by email or phone, via QueryEngine (no raw SQL).
+  const lookupEmail = adapterHint?.email ?? heuristicEmail(input.senderIdentifier)
+  const lookupPhone = adapterHint?.phone ?? heuristicPhone(input.senderIdentifier)
+
+  let matchedPersonId: string | undefined
+  if ((lookupEmail || lookupPhone) && deps.container) {
+    matchedPersonId = await lookupCustomerPersonId({
+      container: deps.container,
+      scope: input.scope,
+      email: lookupEmail,
+      phone: lookupPhone,
+    })
+  }
+
+  return {
+    ...(adapterHint ?? {}),
+    email: lookupEmail,
+    phone: lookupPhone,
+    displayName: adapterHint?.displayName ?? input.senderDisplayName,
+    matchedPersonId: matchedPersonId ?? adapterHint?.matchedPersonId,
+  }
+}
+
+async function runAdapterResolve(input: ContactResolverInput): Promise<ContactHint | null> {
+  if (typeof input.adapter.resolveContact !== 'function') return null
+  try {
+    return (
+      (await input.adapter.resolveContact({
+        senderIdentifier: input.senderIdentifier,
+        senderDisplayName: input.senderDisplayName,
+        channelMetadata: input.channelMetadata,
+        credentials: input.credentials,
+        scope: input.scope,
+      })) ?? null
+    )
+  } catch {
+    // The adapter is best-effort. A failure does not block ingest; we just lose
+    // the optional CRM match. Errors are not propagated.
+    return null
+  }
+}
+
+async function lookupCustomerPersonId(params: {
+  container: ResolveContactDeps['container']
+  scope: TenantScope
+  email?: string
+  phone?: string
+}): Promise<string | undefined> {
+  // Under tenant encryption, `primary_email`/`primary_phone` are stored as
+  // ciphertext, so a plaintext equality filter on the base column both hits the
+  // §16 "no querying an encrypted column by value" footgun and never matches.
+  // Skip the fast lookup in that case (it would only ever return nothing) — the
+  // authoritative CRM link is created by the customers `link-channel-message`
+  // subscriber, which does an in-memory decrypted comparison. A blind-index
+  // column is the proper fast-path fix here (same follow-up as
+  // `customers/lib/findPeopleByAddresses`).
+  if (isTenantDataEncryptionEnabled()) return undefined
+
+  let queryEngine: QueryEngineLike | null = null
+  try {
+    queryEngine = params.container.resolve<QueryEngineLike>('queryEngine')
+  } catch {
+    return undefined
+  }
+  if (!queryEngine || typeof queryEngine.query !== 'function') return undefined
+
+  const filter = buildPersonLookupFilter(params.email, params.phone)
+  if (!filter) return undefined
+
+  try {
+    const rows = await queryEngine.query('customers:customer_entity', {
+      tenantId: params.scope.tenantId,
+      organizationId: params.scope.organizationId,
+      filter,
+      limit: 1,
+    })
+    const first = rows?.[0]
+    const id = first && typeof first.id === 'string' ? (first.id as string) : undefined
+    return id
+  } catch {
+    return undefined
+  }
+}
+
+function buildPersonLookupFilter(email?: string, phone?: string): Record<string, unknown> | null {
+  if (email) return { primary_email: email, kind: 'person' }
+  if (phone) return { primary_phone: phone, kind: 'person' }
+  return null
+}
+
+function heuristicEmail(senderIdentifier: string): string | undefined {
+  if (!senderIdentifier.includes('@')) return undefined
+  // Don't second-guess provider-supplied data; just check it's email-shaped.
+  return senderIdentifier.includes('.') ? senderIdentifier : undefined
+}
+
+function heuristicPhone(senderIdentifier: string): string | undefined {
+  // Plain heuristic: +CC followed by 6+ digits. Real phone validation is the
+  // adapter's job (the email integration spec elaborates IMAP paths).
+  if (/^\+\d{6,}$/.test(senderIdentifier)) return senderIdentifier
+  return undefined
+}

package/src/modules/communication_channels/lib/credential-refresh.ts

@@ -0,0 +1,197 @@
+import type {
+  ChannelAdapter,
+  OAuthClientConfig,
+  RefreshedCredentials,
+  TenantScope,
+} from './adapter'
+import { resolveOAuthClientCredentials } from './oauth-client-config'
+
+/**
+ * Optional credentials-service shape — matches the integrations module's
+ * `CredentialsService`. We keep this loose so the helper compiles even when
+ * the integrations module is disabled in a downstream app (the helper just
+ * skips persistence in that case).
+ */
+/**
+ * Matches the real `CredentialsService.save(integrationId, credentials, scope)`
+ * signature from `packages/core/src/modules/integrations/lib/credentials-service.ts`.
+ * The legacy call sites had this argument order inverted; that bug was the root
+ * cause of C1 in the 2026-05-26 review.
+ *
+ * `scope.userId` (added 2026-05-26 for per-user channels) lets the credentials
+ * service write to a user-scoped row instead of overwriting the tenant-wide row.
+ */
+type CredentialsScope = TenantScope & { userId?: string | null }
+type CredentialsServiceLike = {
+  resolve: (integrationId: string, scope: CredentialsScope) => Promise<Record<string, unknown> | null>
+  save?: (integrationId: string, credentials: Record<string, unknown>, scope: CredentialsScope) => Promise<void>
+}
+
+export type RefreshCredentialsIfNeededInput = {
+  adapter: ChannelAdapter
+  channelId: string
+  /** Current decrypted credential blob. May contain `expiresAt` (Date or ISO string). */
+  credentials: Record<string, unknown>
+  scope: CredentialsScope
+  /** Refresh window — refresh when token expires within this many ms. Defaults to 60s. */
+  refreshWindowMs?: number
+  /** Force a refresh regardless of expiry — used after a 401 response from the provider. */
+  force?: boolean
+}
+
+export type RefreshCredentialsIfNeededResult = {
+  refreshed: boolean
+  /** The latest credential blob to use for the outbound call. */
+  credentials: Record<string, unknown>
+}
+
+const DEFAULT_REFRESH_WINDOW_MS = 60_000
+
+/**
+ * In-process single-flight for credential refresh, keyed by `channelId`. The
+ * outbound-delivery worker runs at concurrency 10 in ONE process, so two
+ * concurrent sends on the same channel can both pass `shouldRefresh` and both
+ * call `adapter.refreshCredentials`. With rotating refresh-token providers
+ * (Gmail) the second exchange invalidates the first's token and
+ * flaps the channel to `requires_reauth`. Coalescing concurrent refreshes for
+ * the same channel onto one in-flight promise prevents that race for the common
+ * single-process case. Entries are deleted in `finally` once settled.
+ */
+const inFlightRefreshes = new Map<string, Promise<RefreshCredentialsIfNeededResult>>()
+
+/**
+ * Refresh OAuth credentials when an access token is near expiry, or when the
+ * caller forces it (e.g. after a 401 response).
+ *
+ * Behaviour:
+ *   - No-op when the adapter does not implement `refreshCredentials?`.
+ *   - No-op when the credential blob has no `expiresAt` AND `force !== true`.
+ *   - Returns the refreshed credentials in-memory; persistence to
+ *     `integration_credentials` happens via the `CredentialsService` if it
+ *     is registered AND exposes `save()` (best-effort — failures are logged
+ *     but don't block the outbound call).
+ */
+export async function refreshCredentialsIfNeeded(
+  input: RefreshCredentialsIfNeededInput,
+  deps?: { credentialsService?: CredentialsServiceLike | null; logger?: (...args: unknown[]) => void },
+): Promise<RefreshCredentialsIfNeededResult> {
+  const log = deps?.logger ?? (() => {})
+  if (typeof input.adapter.refreshCredentials !== 'function') {
+    return { refreshed: false, credentials: input.credentials }
+  }
+
+  const refreshWindow = input.refreshWindowMs ?? DEFAULT_REFRESH_WINDOW_MS
+  if (!input.force && !shouldRefresh(input.credentials, refreshWindow)) {
+    return { refreshed: false, credentials: input.credentials }
+  }
+
+  // Coalesce concurrent refreshes for the same channel onto one in-flight
+  // promise so rotating refresh tokens are not exchanged twice in parallel.
+  const existing = inFlightRefreshes.get(input.channelId)
+  if (existing) return existing
+
+  const refreshCredentials = input.adapter.refreshCredentials.bind(input.adapter)
+  const refreshPromise = runRefresh(input, refreshCredentials, deps, log).finally(() => {
+    inFlightRefreshes.delete(input.channelId)
+  })
+  inFlightRefreshes.set(input.channelId, refreshPromise)
+  return refreshPromise
+}
+
+async function runRefresh(
+  input: RefreshCredentialsIfNeededInput,
+  refreshCredentials: NonNullable<ChannelAdapter['refreshCredentials']>,
+  deps: { credentialsService?: CredentialsServiceLike | null; logger?: (...args: unknown[]) => void } | undefined,
+  log: (...args: unknown[]) => void,
+): Promise<RefreshCredentialsIfNeededResult> {
+  // Resolve the tenant's OAuth client config (clientId/clientSecret) the admin
+  // stored under the `channel_<providerKey>` integration at TENANT scope
+  // (userId = null). The adapter uses it for the token-endpoint call. We always
+  // resolve at tenant scope here — never the channel's per-user scope — because
+  // the per-user row holds the user's tokens, not the client app credentials.
+  let oauthClient: OAuthClientConfig | undefined
+  if (deps?.credentialsService) {
+    try {
+      const raw = await resolveOAuthClientCredentials(
+        deps.credentialsService,
+        input.adapter.providerKey,
+        { tenantId: input.scope.tenantId, organizationId: input.scope.organizationId },
+      )
+      oauthClient = safeParseOAuthClient(raw)
+    } catch (resolveErr) {
+      log(
+        '[communication_channels] resolving OAuth client config failed:',
+        resolveErr instanceof Error ? resolveErr.message : resolveErr,
+      )
+    }
+  }
+
+  let result: RefreshedCredentials
+  try {
+    result = await refreshCredentials({
+      channelId: input.channelId,
+      credentials: input.credentials,
+      scope: input.scope,
+      oauthClient,
+    })
+  } catch (err) {
+    log('[communication_channels] refreshCredentials failed:', err instanceof Error ? err.message : err)
+    // Return current credentials — caller may still attempt the send with the old token.
+    return { refreshed: false, credentials: input.credentials }
+  }
+
+  const next = result?.credentials ?? input.credentials
+  if (deps?.credentialsService?.save) {
+    try {
+      await deps.credentialsService.save(
+        `channel_${input.adapter.providerKey}`,
+        result.expiresAt ? { ...next, expiresAt: result.expiresAt.toISOString() } : next,
+        input.scope,
+      )
+    } catch (saveErr) {
+      log('[communication_channels] persisting refreshed credentials failed:', saveErr instanceof Error ? saveErr.message : saveErr)
+    }
+  }
+
+  return { refreshed: true, credentials: next }
+}
+
+function shouldRefresh(credentials: Record<string, unknown>, windowMs: number): boolean {
+  const expiresAtRaw = credentials?.expiresAt
+  if (!expiresAtRaw) return false
+  const expiresAt = parseExpiresAt(expiresAtRaw)
+  if (!expiresAt) return false
+  return expiresAt.getTime() - Date.now() <= windowMs
+}
+
+function parseExpiresAt(raw: unknown): Date | null {
+  if (raw instanceof Date) return Number.isFinite(raw.getTime()) ? raw : null
+  if (typeof raw === 'string' || typeof raw === 'number') {
+    const date = new Date(raw)
+    return Number.isFinite(date.getTime()) ? date : null
+  }
+  return null
+}
+
+/**
+ * Parse a raw `channel_<provider>` client-credential row into the
+ * `OAuthClientConfig` shape adapters expect. Returns `undefined` when the row is
+ * missing or malformed — adapters then fall back to the deprecated
+ * `credentials._client` read path (one minor-release deprecation per Spec A).
+ */
+function safeParseOAuthClient(raw: unknown): OAuthClientConfig | undefined {
+  if (!raw || typeof raw !== 'object') return undefined
+  const record = raw as Record<string, unknown>
+  const clientId = typeof record.clientId === 'string' ? record.clientId : undefined
+  if (!clientId) return undefined
+  const clientSecret =
+    typeof record.clientSecret === 'string' ? record.clientSecret : undefined
+  const scopes = Array.isArray(record.scopes)
+    ? record.scopes.filter((value): value is string => typeof value === 'string')
+    : undefined
+  return {
+    clientId,
+    ...(clientSecret !== undefined ? { clientSecret } : {}),
+    ...(scopes !== undefined ? { scopes } : {}),
+  }
+}

package/src/modules/communication_channels/lib/dead-letter.ts

@@ -0,0 +1,87 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { ChannelIngestDeadLetter } from '../data/entities'
+import type { NormalizedInboundMessage } from './adapter'
+
+const DEAD_LETTER_RAW_BODY_MAX_BYTES_DEFAULT = 32_768
+
+export function extractExternalUid(message: NormalizedInboundMessage): string | null {
+  const meta = message.channelMetadata as Record<string, unknown> | undefined
+  if (meta && typeof meta.uid === 'string') return meta.uid
+  if (meta && typeof meta.uid === 'number') return String(meta.uid)
+  return null
+}
+
+/**
+ * First N *bytes* of the raw body, for dead-letter forensics. Counts bytes (not
+ * UTF-16 code units) so a multi-byte body cannot blow past the intended cap.
+ */
+export function truncateRawBody(message: NormalizedInboundMessage): string | null {
+  const envCap = Number.parseInt(process.env.OM_CHANNEL_DEAD_LETTER_RAW_BODY_MAX_BYTES ?? '', 10)
+  const cap = Number.isFinite(envCap) && envCap > 0 ? envCap : DEAD_LETTER_RAW_BODY_MAX_BYTES_DEFAULT
+  const body = message.body ?? ''
+  if (body.length === 0) return null
+  const buf = Buffer.from(body, 'utf-8')
+  if (buf.byteLength <= cap) return body
+  return `${buf.subarray(0, cap).toString('utf-8')}…[truncated]`
+}
+
+export interface WriteIngestDeadLetterArgs {
+  em: EntityManager
+  scope: { tenantId: string; organizationId?: string | null }
+  channel: { id: string; providerKey: string }
+  message: NormalizedInboundMessage
+  err: unknown
+  errorMessage: string
+}
+
+/**
+ * Persist a `ChannelIngestDeadLetter` row for a permanently-failed inbound
+ * message so an operator can replay it later. Best-effort: a failure to write
+ * the dead-letter is logged but never thrown, so a bad message cannot block the
+ * caller from advancing its cursor.
+ *
+ * Idempotent on `(channelId, externalMessageId)`: a replayed page that fails the
+ * same message again is a no-op, so the dead-letter table never accumulates
+ * duplicate rows for the same poison message.
+ */
+export async function writeIngestDeadLetter(args: WriteIngestDeadLetterArgs): Promise<void> {
+  const { em, scope, channel, message, err, errorMessage } = args
+  const externalMessageId = message.externalMessageId ?? null
+  try {
+    if (externalMessageId) {
+      const existing = await findOneWithDecryption(
+        em,
+        ChannelIngestDeadLetter,
+        {
+          tenantId: scope.tenantId,
+          organizationId: scope.organizationId ?? null,
+          channelId: channel.id,
+          externalMessageId,
+        },
+        undefined,
+        { tenantId: scope.tenantId, organizationId: scope.organizationId ?? null },
+      )
+      if (existing) return
+    }
+    const deadLetter = em.create(ChannelIngestDeadLetter, {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId ?? null,
+      channelId: channel.id,
+      providerKey: channel.providerKey,
+      externalUid: extractExternalUid(message),
+      externalMessageId,
+      errorClass: err instanceof Error ? err.name : 'Error',
+      errorMessage,
+      rawBody: truncateRawBody(message),
+    })
+    em.persist(deadLetter)
+    await em.flush()
+  } catch (ddlErr) {
+    console.error(
+      `[communication_channels:dead-letter] failed to record dead-letter for channel ${channel.id}: ${
+        ddlErr instanceof Error ? ddlErr.message : String(ddlErr)
+      }`,
+    )
+  }
+}

package/src/modules/communication_channels/lib/email-capabilities.ts

@@ -0,0 +1,60 @@
+import type { ChannelCapabilities } from './adapter'
+
+/**
+ * Shared default attachment ceiling for email providers (Gmail allows
+ * more, but larger uploads need resumable/upload-session APIs we don't use, so
+ * all providers cap at the same conservative value).
+ */
+export const EMAIL_MAX_ATTACHMENT_BYTES = 25_000_000
+
+/**
+ * Baseline capability profile shared by every email channel provider. Providers
+ * spread this and override only what genuinely differs (e.g. `deleteMessage`).
+ *
+ * `fileSharing: false` until a provider's `convertOutbound` stitches attachment
+ * bytes into the sent message — advertising `true` would silently drop bytes.
+ */
+export const baseEmailCapabilities: ChannelCapabilities = {
+  // Core
+  threading: true,
+  richText: true,
+  fileSharing: false,
+  maxFileSize: EMAIL_MAX_ATTACHMENT_BYTES,
+  supportedMimeTypes: [
+    'image/png',
+    'image/jpeg',
+    'image/gif',
+    'image/webp',
+    'application/pdf',
+    'application/zip',
+    'application/octet-stream',
+    'text/plain',
+    'text/html',
+    'text/csv',
+  ],
+  readReceipts: false,
+  deliveryReceipts: false,
+  typingIndicators: false,
+
+  // Extended
+  reactions: false,
+  multiReactionPerUser: false,
+  editMessage: false,
+  deleteMessage: false,
+  presence: false,
+  richBlocks: false,
+  interactiveComponents: false,
+  inlineImages: true,
+  conversationHistory: true,
+  contactCards: false,
+  locationSharing: false,
+  voiceNotes: false,
+  stickers: false,
+
+  // Body formats
+  supportedBodyFormats: ['text', 'html'],
+  maxBodyLength: 5_000_000,
+
+  // Polling (real-time push deferred to v2 for all email providers)
+  realtimePush: false,
+}

package/src/modules/communication_channels/lib/email-contact.ts

@@ -0,0 +1,17 @@
+import type { ContactHint, ResolveContactInput } from './adapter'
+
+/**
+ * Shared `resolveContact` for email providers. An email sender identifier *is*
+ * the contact email, so the hint is a direct passthrough; non-email identifiers
+ * (or empty senders) yield `null` and the hub falls back to its own resolution.
+ */
+export async function emailResolveContact(input: ResolveContactInput): Promise<ContactHint | null> {
+  if (!input.senderIdentifier) return null
+  if (input.senderIdentifier.includes('@')) {
+    return {
+      email: input.senderIdentifier,
+      displayName: input.senderDisplayName,
+    }
+  }
+  return null
+}