@open-mercato/core 0.7.1-develop.7149.1.7efa6e1612 → 0.7.1-develop.7151.1.00d0391847

package/src/modules/communication_channels/lib/system-email-provider-config.ts

@@ -0,0 +1,62 @@
+import { normalizeEnvString } from '@open-mercato/shared/lib/email/config'
+
+type SystemEmailProviderConfigContext = {
+  fromAddress: string
+}
+
+export const DEFAULT_SYSTEM_EMAIL_PROVIDER = 'resend'
+
+/**
+ * The provider key `sendSystemEmail` resolves channels and credentials against.
+ *
+ * Lives here rather than in `system-email.ts` so a provider package's `setup.ts` can read it without
+ * importing the send path — that module pulls the ORM and the React renderer in behind it, and a
+ * preset that runs at tenant seeding has no business loading either.
+ */
+export function resolveSystemEmailProvider(): string {
+  return normalizeEnvString(process.env.SYSTEM_EMAIL_PROVIDER) ?? DEFAULT_SYSTEM_EMAIL_PROVIDER
+}
+
+/**
+ * Whether a provider package's env preset should seed anything for this instance.
+ *
+ * Only the selected provider seeds. Without this gate a preset fires off whatever env variables
+ * happen to be present, and `AWS_REGION` in particular is a general-purpose variable this repo
+ * already ships uncommented for vector search — so an instance sending through Resend would get an
+ * `isEnabled: true` SES integration and a `status: 'connected'` SES channel it never configured.
+ */
+export function isSelectedSystemEmailProvider(providerKey: string): boolean {
+  return resolveSystemEmailProvider() === providerKey
+}
+
+export type SystemEmailProviderConfigResolver = {
+  providerKey: string
+  isConfigured: () => boolean
+  resolveCredentials: (ctx: SystemEmailProviderConfigContext) => Record<string, unknown>
+}
+
+const SYSTEM_EMAIL_PROVIDER_CONFIG_REGISTRY = Symbol.for(
+  'open-mercato.communication-channels.system-email-provider-config',
+)
+
+type RegistryGlobal = typeof globalThis & {
+  [SYSTEM_EMAIL_PROVIDER_CONFIG_REGISTRY]?: Map<string, SystemEmailProviderConfigResolver>
+}
+
+function getRegistry(): Map<string, SystemEmailProviderConfigResolver> {
+  const root = globalThis as RegistryGlobal
+  if (!root[SYSTEM_EMAIL_PROVIDER_CONFIG_REGISTRY]) {
+    root[SYSTEM_EMAIL_PROVIDER_CONFIG_REGISTRY] = new Map()
+  }
+  return root[SYSTEM_EMAIL_PROVIDER_CONFIG_REGISTRY]
+}
+
+export function registerSystemEmailProviderConfigResolver(resolver: SystemEmailProviderConfigResolver): void {
+  getRegistry().set(resolver.providerKey, resolver)
+}
+
+export function getSystemEmailProviderConfigResolver(
+  providerKey: string,
+): SystemEmailProviderConfigResolver | undefined {
+  return getRegistry().get(providerKey)
+}

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

@@ -0,0 +1,316 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import type { ResolvedEmailPayload } from '@open-mercato/shared/lib/email/send'
+import { normalizeEnvString } from '@open-mercato/shared/lib/email/config'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { ChannelAdapterRegistry } from './registry'
+import { htmlToText } from './email-mime'
+import {
+  DEFAULT_SYSTEM_EMAIL_PROVIDER,
+  getSystemEmailProviderConfigResolver,
+  resolveSystemEmailProvider,
+} from './system-email-provider-config'
+import { isTestChannelSeedingEnabled, TEST_SEED_PROVIDER_KEY } from './test-seed'
+import { ensureSystemEmailChannel } from './ensure-system-email-channel'
+import { CommunicationChannel } from '../data/entities'
+
+export { DEFAULT_SYSTEM_EMAIL_PROVIDER }
+
+const logger = createLogger('communication_channels')
+
+type CredentialsServiceLike = {
+  resolve: (
+    integrationId: string,
+    scope: { organizationId: string; tenantId: string; userId?: string | null },
+  ) => Promise<Record<string, unknown> | null>
+}
+
+type ResolvedSystemEmailChannel = Pick<CommunicationChannel, 'providerKey' | 'channelType' | 'organizationId'>
+
+/**
+ * Outcome of resolving which channel a system email should go out through.
+ *
+ * `hasTenantChannel` drives the credential posture and is the whole point of the split: a tenant that
+ * has an explicitly configured Hub channel MUST fail closed when its credentials are missing (never
+ * silently borrow the instance-wide env key), while a tenant with no channel at all is an instance
+ * that simply has not been migrated onto the Communications Hub yet and MUST keep working off env.
+ */
+type ResolvedSystemEmailTarget = {
+  channel: ResolvedSystemEmailChannel
+  hasTenantChannel: boolean
+}
+
+export function isSystemEmailTransportConfigured(): boolean {
+  return getSystemEmailProviderConfigResolver(resolveSystemEmailProvider())?.isConfigured() ?? false
+}
+
+async function renderReactEmail(react: ResolvedEmailPayload['react']): Promise<string | undefined> {
+  if (!react) return undefined
+  const { renderToStaticMarkup } = await import('react-dom/server')
+  const markup = renderToStaticMarkup(react)
+  return markup.startsWith('<!doctype html>') || markup.startsWith('<!DOCTYPE html>')
+    ? markup
+    : `<!doctype html>${markup}`
+}
+
+async function resolveEmailBody(payload: ResolvedEmailPayload): Promise<{
+  html?: string
+  text?: string
+  body: string
+  bodyFormat: 'text' | 'html'
+}> {
+  const html = payload.html ?? (await renderReactEmail(payload.react))
+  const text = payload.text ?? (html ? htmlToText(html) : undefined)
+  if (html) return { html, text, body: html, bodyFormat: 'html' }
+  if (text) return { text, body: text, bodyFormat: 'text' }
+  throw new Error('EMAIL_BODY_NOT_CONFIGURED: provide react, html, or text')
+}
+
+/**
+ * Locate the tenant's system email channel.
+ *
+ * Two probes, both inside the caller's own scope: the caller's organization first, then the
+ * organization-agnostic (`organization_id IS NULL`) row that represents a genuinely tenant-wide
+ * channel. A channel belonging to a *different* organization is deliberately never used — organization
+ * is a scoping boundary, and borrowing another organization's channel would send through credentials
+ * that organization owns. A caller whose organization has no channel falls through to the
+ * instance-wide environment credentials instead, which cross no boundary at all.
+ */
+async function findTenantSystemEmailChannel(
+  em: EntityManager,
+  payload: ResolvedEmailPayload,
+  providerKey: string,
+): Promise<CommunicationChannel | null> {
+  const tenantId = payload.tenantId as string
+  const dscope = { tenantId, organizationId: payload.organizationId ?? null }
+  const base = {
+    providerKey,
+    channelType: 'email',
+    tenantId,
+    userId: null,
+    deletedAt: null,
+  }
+
+  const organizationScopes: Array<string | null> = [payload.organizationId ?? null]
+  if (payload.organizationId) organizationScopes.push(null)
+
+  for (const organizationId of organizationScopes) {
+    const found = await findOneWithDecryption(
+      em,
+      CommunicationChannel,
+      { ...base, organizationId },
+      undefined,
+      dscope,
+    )
+    if (found) return found
+  }
+  return null
+}
+
+async function resolveSystemEmailChannel(
+  em: EntityManager,
+  payload: ResolvedEmailPayload,
+): Promise<ResolvedSystemEmailTarget> {
+  const providerKey = resolveSystemEmailProvider()
+  const envTarget: ResolvedSystemEmailTarget = {
+    channel: {
+      providerKey,
+      channelType: 'email',
+      organizationId: payload.organizationId ?? null,
+    },
+    hasTenantChannel: false,
+  }
+
+  if (!payload.tenantId) {
+    return { ...envTarget, channel: { ...envTarget.channel, organizationId: null } }
+  }
+
+  const dscope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId ?? null,
+  }
+  const explicitChannelId = normalizeEnvString(process.env.SYSTEM_EMAIL_CHANNEL_ID)
+
+  // An operator who pinned SYSTEM_EMAIL_CHANNEL_ID asked for exactly one channel. Honour that
+  // literally and never widen the search or fall back to env — a silent substitution would send
+  // through a provider the operator deliberately did not choose.
+  //
+  // The pin narrows the search; it does not lift the organization boundary. A pinned id is accepted
+  // only when the row is the caller's own organization or the tenant-wide (`organization_id IS NULL`)
+  // one the setting is documented to name. Matching on the id alone would let a pin aimed at one
+  // organization's channel send every other organization's mail through credentials that
+  // organization owns — the same borrowing `findTenantSystemEmailChannel` refuses.
+  const channel = explicitChannelId
+    ? await findOneWithDecryption(
+        em,
+        CommunicationChannel,
+        {
+          id: explicitChannelId,
+          channelType: 'email',
+          tenantId: payload.tenantId,
+          userId: null,
+          deletedAt: null,
+          $or: [{ organizationId: payload.organizationId ?? null }, { organizationId: null }],
+        },
+        undefined,
+        dscope,
+      )
+    : await findTenantSystemEmailChannel(em, payload, providerKey)
+
+  if (channel) {
+    if (!channel.isActive || channel.status !== 'connected') {
+      throw new Error(`SYSTEM_EMAIL_CHANNEL_UNAVAILABLE: channel is ${channel.status}`)
+    }
+    return { channel, hasTenantChannel: true }
+  }
+
+  if (explicitChannelId) {
+    throw new Error(
+      `SYSTEM_EMAIL_CHANNEL_NOT_CONFIGURED: SYSTEM_EMAIL_CHANNEL_ID '${explicitChannelId}' matches no active channel this organization may use`,
+    )
+  }
+
+  if (isTestChannelSeedingEnabled() && providerKey === TEST_SEED_PROVIDER_KEY) {
+    return {
+      channel: { providerKey: TEST_SEED_PROVIDER_KEY, channelType: 'email', organizationId: payload.organizationId ?? null },
+      hasTenantChannel: false,
+    }
+  }
+
+  // No channel row for this tenant. This is the ordinary state of an instance that upgraded into the
+  // Communications Hub: tenants predate the feature, so nothing ever seeded a channel for them.
+  // Do not decide here — `sendSystemEmail` still has to check whether the tenant configured the
+  // provider through the integrations UI before it considers the instance-wide env credentials.
+  return envTarget
+}
+
+function resolveEnvCredentials(providerKey: string, fromAddress: string): Record<string, unknown> {
+  return getSystemEmailProviderConfigResolver(providerKey)?.resolveCredentials({ fromAddress }) ?? { fromAddress }
+}
+
+/**
+ * Decide which credentials a tenant-scoped send uses.
+ *
+ * Three cases, in priority order:
+ *
+ * 1. The tenant has credentials stored for the provider (seeded, or saved through
+ *    `/backend/integrations/channel_<provider>`) — always win. When no Hub channel row exists yet we
+ *    also create one, so configuring the integration in the admin UI produces a usable channel
+ *    instead of credentials nothing reads.
+ * 2. The tenant has a configured channel but no credentials — **fail closed**. Borrowing the
+ *    instance key here would send a tenant's mail through a provider account it did not choose.
+ * 3. The tenant has neither — fall back to the instance-wide env credentials. This is the pre-Hub
+ *    behaviour and the upgrade path: env credentials are instance-wide by definition, so this leaks
+ *    nothing across tenants, and without it every tenant that predates the Hub loses all mail.
+ */
+async function resolveTenantCredentials(
+  container: AppContainer,
+  em: EntityManager,
+  payload: ResolvedEmailPayload,
+  channel: ResolvedSystemEmailChannel,
+  hasTenantChannel: boolean,
+): Promise<Record<string, unknown>> {
+  const tenantId = payload.tenantId as string
+  const organizationId = channel.organizationId ?? payload.organizationId ?? tenantId
+  const credentialsService = container.resolve('integrationCredentialsService') as CredentialsServiceLike
+  const resolvedCredentials = await credentialsService.resolve(`channel_${channel.providerKey}`, {
+    tenantId,
+    organizationId,
+    userId: null,
+  })
+
+  if (resolvedCredentials) {
+    if (!hasTenantChannel) {
+      await ensureSystemEmailChannel(em, {
+        tenantId,
+        organizationId,
+        providerKey: channel.providerKey,
+        externalIdentifier: typeof resolvedCredentials.fromAddress === 'string' ? resolvedCredentials.fromAddress : payload.from,
+      })
+    }
+    return resolvedCredentials
+  }
+
+  if (hasTenantChannel) {
+    throw new Error(
+      `SYSTEM_EMAIL_CREDENTIALS_NOT_CONFIGURED: configure tenant credentials for '${channel.providerKey}'`,
+    )
+  }
+
+  if (!isSystemEmailTransportConfigured()) {
+    throw new Error('SYSTEM_EMAIL_CHANNEL_NOT_CONFIGURED: configure a tenant-wide email channel')
+  }
+
+  logger.warn('Sending system email with instance-wide environment credentials', {
+    tenantId,
+    providerKey: channel.providerKey,
+    reason: `no tenant email channel or credentials configured for '${channel.providerKey}'`,
+    remedy: `run 'yarn mercato seed:defaults --module channel_${channel.providerKey}' to move this tenant onto the Communications Hub`,
+  })
+  return resolveEnvCredentials(channel.providerKey, payload.from)
+}
+
+/**
+ * Choose the address a system email actually leaves from.
+ *
+ * The tenant's configured sender wins whenever the caller did not name one itself. `sendEmail` always
+ * fills `from` in — from `NOTIFICATIONS_EMAIL_FROM` / `EMAIL_FROM` / `ADMIN_EMAIL` — so an adapter that
+ * merely falls back to its credentials when `from` is missing would never reach the tenant's value, and
+ * the "From address" saved in the integrations UI would be inert. A caller that passed an explicit
+ * `from` meant it, and keeps it.
+ */
+function resolveOutboundFromAddress(
+  payload: ResolvedEmailPayload,
+  credentials: Record<string, unknown>,
+): string {
+  if (!payload.fromIsInstanceDefault) return payload.from
+  const configured = credentials.fromAddress
+  return typeof configured === 'string' && configured.trim().length > 0 ? configured : payload.from
+}
+
+export async function sendSystemEmail(
+  container: AppContainer,
+  payload: ResolvedEmailPayload,
+): Promise<void> {
+  const em = (container.resolve('em') as EntityManager).fork()
+  const { channel, hasTenantChannel } = await resolveSystemEmailChannel(em, payload)
+  const registry = container.resolve('channelAdapterRegistry') as ChannelAdapterRegistry
+  const adapter = registry.get(channel.providerKey)
+  if (!adapter) {
+    throw new Error(
+      `[internal] No ChannelAdapter registered for providerKey '${channel.providerKey}'. Enable the provider module.`,
+    )
+  }
+
+  const credentials = payload.tenantId
+    ? await resolveTenantCredentials(container, em, payload, channel, hasTenantChannel)
+    : resolveEnvCredentials(channel.providerKey, payload.from)
+
+  const body = await resolveEmailBody(payload)
+  const converted = await adapter.convertOutbound({
+    body: body.body,
+    bodyFormat: body.bodyFormat,
+    channelMetadata: {
+      to: payload.to,
+      subject: payload.subject,
+      from: resolveOutboundFromAddress(payload, credentials),
+      replyTo: payload.replyTo,
+      attachments: payload.attachments,
+    },
+  })
+
+  const sendResult = await adapter.sendMessage({
+    content: converted.content,
+    credentials,
+    scope: {
+      tenantId: payload.tenantId ?? 'system',
+      organizationId: payload.organizationId ?? payload.tenantId ?? 'system',
+    },
+    metadata: converted.metadata,
+  })
+
+  if (sendResult.status === 'failed') {
+    throw new Error(sendResult.error ?? `SYSTEM_EMAIL_SEND_FAILED: ${channel.providerKey}`)
+  }
+}

package/src/modules/communication_channels/lib/test-seed.ts

@@ -1,3 +1,7 @@
+import { appendFile, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { timingSafeEqual } from 'node:crypto'
+import path from 'node:path'
+import type { EntityManager } from '@mikro-orm/postgresql'
 import type {
   ChannelAdapter,
   ChannelCapabilities,
@@ -15,6 +19,7 @@ import type {
 } from './adapter'
 import { baseEmailCapabilities } from './email-capabilities'
 import { hasChannelAdapter, registerChannelAdapter } from './adapter-registry-singleton'
+import { registerSystemEmailProviderConfigResolver } from './system-email-provider-config'
 
 /**
  * Test-only channel seeding support.
@@ -56,6 +61,18 @@ export const TEST_SEED_CHAT_PROVIDER_KEY = '__test_seed_chat__'
 
 /** Env flag that unlocks test-only channel seeding. Off in production. */
 export const TEST_CHANNEL_SEEDING_ENV = 'OM_ENABLE_TEST_CHANNEL_SEEDING'
+export const TEST_EMAIL_CAPTURE_ACCESS_TOKEN_ENV = 'OM_TEST_EMAIL_CAPTURE_ACCESS_TOKEN'
+export const TEST_EMAIL_CAPTURE_CORRELATION_TOKEN_ENV = 'OM_TEST_EMAIL_CAPTURE_CORRELATION_TOKEN'
+/**
+ * Where the Hub's tenant-scoped capture is written.
+ *
+ * Deliberately not `OM_TEST_EMAIL_CAPTURE_PATH`: that one belongs to the unscoped capture in
+ * `@open-mercato/shared/lib/email/send`, which writes a different record shape to a path the repo
+ * also ships a committed fixture for. Pointing both mechanisms at one file made this module parse
+ * foreign records and let `clear-capture` rewrite the other mechanism's fixtures. Two mechanisms,
+ * two files.
+ */
+export const TEST_SYSTEM_EMAIL_CAPTURE_PATH_ENV = 'OM_TEST_SYSTEM_EMAIL_CAPTURE_PATH'
 
 /**
  * True only when the test-seeding env flag is explicitly enabled. Accepts the
@@ -68,6 +85,173 @@ export function isTestChannelSeedingEnabled(): boolean {
   return ['1', 'true', 'yes', 'on'].includes(raw.trim().toLowerCase())
 }
 
+export type TestSeedCapturedMessage = {
+  capturedAt: string
+  externalMessageId: string
+  conversationId?: string
+  content: SendMessageInput['content']
+  scope: SendMessageInput['scope']
+  metadata?: SendMessageInput['metadata']
+  captureCorrelationToken?: string
+}
+
+type TestSeedCaptureScope = {
+  tenantId: string
+  organizationId: string | null
+}
+
+export type TestSeedCaptureOptions = {
+  systemRecipient?: string
+  captureCorrelationToken?: string
+}
+
+export async function createTestSeedPlatformMessage(
+  em: EntityManager,
+  input: {
+    providerKey: string
+    threadId?: string
+    senderUserId: string
+    subject?: string
+    bodyText?: string
+    channelId: string
+    tenantId: string
+    organizationId: string | null
+  },
+): Promise<string | null> {
+  const rows = (await em.getConnection().execute(
+    `INSERT INTO messages
+       (type, thread_id, sender_user_id, subject, body, body_format, priority, status,
+        is_draft, sent_at, visibility, source_entity_type, source_entity_id,
+        tenant_id, organization_id, created_at, updated_at)
+     VALUES
+       (?, ?, ?, ?, ?, 'text', 'normal', 'sent',
+        false, now(), 'public', 'communication_channels.test_seed_inbound', ?,
+        ?, ?, now(), now())
+     RETURNING id`,
+    [
+      `channel.${input.providerKey}`,
+      input.threadId ?? null,
+      input.senderUserId,
+      input.subject ?? '(no subject)',
+      input.bodyText ?? '',
+      input.channelId,
+      input.tenantId,
+      input.organizationId,
+    ],
+  )) as Array<{ id: string }>
+  return rows[0]?.id ?? null
+}
+
+function normalizeToken(value: string | null | undefined): string | null {
+  if (typeof value !== 'string') return null
+  const normalized = value.trim()
+  return normalized.length >= 32 ? normalized : null
+}
+
+export function isTestEmailCaptureAccessAuthorized(providedToken: string | null): boolean {
+  const expectedToken = normalizeToken(process.env[TEST_EMAIL_CAPTURE_ACCESS_TOKEN_ENV])
+  const normalizedProvidedToken = normalizeToken(providedToken)
+  if (!expectedToken || !normalizedProvidedToken) return false
+  const expected = Buffer.from(expectedToken)
+  const provided = Buffer.from(normalizedProvidedToken)
+  return expected.length === provided.length && timingSafeEqual(expected, provided)
+}
+
+export function resolveTestEmailCaptureCorrelationToken(): string | null {
+  return normalizeToken(process.env[TEST_EMAIL_CAPTURE_CORRELATION_TOKEN_ENV])
+}
+
+function resolveCapturePath(): string {
+  const explicit = process.env[TEST_SYSTEM_EMAIL_CAPTURE_PATH_ENV]?.trim()
+  if (explicit) return path.resolve(explicit)
+  const queueBaseDir = process.env.QUEUE_BASE_DIR?.trim()
+  if (queueBaseDir) return path.resolve(queueBaseDir, '..', 'test-email-capture.jsonl')
+  return path.resolve(process.cwd(), '.mercato', 'test-email-capture.jsonl')
+}
+
+function matchesCaptureScope(
+  message: TestSeedCapturedMessage,
+  scope: TestSeedCaptureScope,
+  options: TestSeedCaptureOptions = {},
+): boolean {
+  if (message.scope.tenantId === scope.tenantId) {
+    const messageOrganizationId = message.scope.organizationId ?? null
+    return messageOrganizationId === scope.organizationId || messageOrganizationId === scope.tenantId
+  }
+
+  if (
+    message.scope.tenantId !== 'system' ||
+    message.scope.organizationId !== 'system' ||
+    !options.systemRecipient ||
+    !options.captureCorrelationToken ||
+    message.captureCorrelationToken !== options.captureCorrelationToken
+  ) {
+    return false
+  }
+
+  const expectedRecipient = options.systemRecipient.trim().toLowerCase()
+  const matchesRecipient = (value: unknown): boolean => {
+    if (typeof value === 'string') return value.trim().toLowerCase() === expectedRecipient
+    if (Array.isArray(value)) return value.some(matchesRecipient)
+    if (!value || typeof value !== 'object') return false
+    return matchesRecipient((value as Record<string, unknown>).address)
+  }
+
+  return matchesRecipient(message.metadata?.to)
+}
+
+async function readTestSeedCapturedMessages(): Promise<TestSeedCapturedMessage[]> {
+  const capturePath = resolveCapturePath()
+  const text = await readFile(capturePath, 'utf8').catch(() => '')
+  return text
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .map((line) => {
+      try {
+        return JSON.parse(line) as TestSeedCapturedMessage
+      } catch {
+        return null
+      }
+    })
+    // A record without a scope is not ours. Skipping instead of throwing keeps a stray or
+    // foreign-shaped line from turning every capture read into a 500.
+    .filter((message): message is TestSeedCapturedMessage => Boolean(message?.scope))
+}
+
+export async function clearTestSeedCapturedMessages(
+  scope: TestSeedCaptureScope,
+  options: TestSeedCaptureOptions = {},
+): Promise<void> {
+  const capturePath = resolveCapturePath()
+  const retained = (await readTestSeedCapturedMessages())
+    .filter((message) => !matchesCaptureScope(message, scope, options))
+  if (retained.length === 0) {
+    await rm(capturePath, { force: true })
+    return
+  }
+  await writeFile(
+    capturePath,
+    `${retained.map((message) => JSON.stringify(message)).join('\n')}\n`,
+    'utf8',
+  )
+}
+
+export async function listTestSeedCapturedMessages(
+  scope: TestSeedCaptureScope,
+  options: TestSeedCaptureOptions = {},
+): Promise<TestSeedCapturedMessage[]> {
+  return (await readTestSeedCapturedMessages()).filter((message) =>
+    matchesCaptureScope(message, scope, options),
+  )
+}
+
+async function captureTestSeedMessage(record: TestSeedCapturedMessage): Promise<void> {
+  const capturePath = resolveCapturePath()
+  await mkdir(path.dirname(capturePath), { recursive: true })
+  await appendFile(capturePath, `${JSON.stringify(record)}\n`, 'utf8')
+}
+
 /**
  * Capabilities for the stub: an email channel that supports neither reactions,
  * edit/delete, nor conversation history — so the strict registry validator
@@ -95,6 +279,15 @@ class TestSeedChannelAdapter implements ChannelAdapter {
     // Synthesize a deterministic-looking RFC2822-style message id; never touches
     // the network. The delivery worker persists this as the external message id.
     const externalMessageId = `test-seed-${Date.now()}-${Math.random().toString(16).slice(2, 10)}@test-seed.local`
+    await captureTestSeedMessage({
+      capturedAt: new Date().toISOString(),
+      externalMessageId,
+      conversationId: input.conversationId,
+      content: input.content,
+      scope: input.scope,
+      metadata: input.metadata,
+      captureCorrelationToken: resolveTestEmailCaptureCorrelationToken() ?? undefined,
+    })
     return {
       externalMessageId,
       conversationId: input.conversationId,
@@ -210,6 +403,11 @@ function getTestSeedChatChannelAdapter(): TestSeedChatChannelAdapter {
  */
 export function ensureTestSeedAdapterRegistered(): void {
   if (!isTestChannelSeedingEnabled()) return
+  registerSystemEmailProviderConfigResolver({
+    providerKey: TEST_SEED_PROVIDER_KEY,
+    isConfigured: isTestChannelSeedingEnabled,
+    resolveCredentials: ({ fromAddress }) => ({ testSeed: true, fromAddress }),
+  })
   if (!hasChannelAdapter(TEST_SEED_PROVIDER_KEY)) {
     registerChannelAdapter(getTestSeedChannelAdapter())
   }