@avelonjs/conformance 0.1.0

package/src/suites/flags.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from 'bun:test'
+import { Invalid, type FlagCapabilities, type FlagDriver } from '@avelonjs/core'
+import { captureFailure, type SuiteContext } from '../harness'
+
+type AssayDriver = FlagDriver<FlagCapabilities>
+
+function assay<TDriver extends AssayDriver>(
+  context: SuiteContext<TDriver>,
+  name: string,
+  assertion: (driver: TDriver) => Promise<void> | void,
+): void {
+  test(name, async () => {
+    const driver = await context.create()
+    try {
+      await assertion(driver)
+    } finally {
+      await context.cleanup?.(driver)
+    }
+  })
+}
+
+async function expectInvalid(operation: () => Promise<unknown>): Promise<Invalid> {
+  const error = await captureFailure(operation)
+  expect(error).toBeInstanceOf(Invalid)
+  if (!(error instanceof Invalid)) throw new Error('Expected Invalid after taxonomy assertion.')
+  expect(error.code).toBe('INVALID')
+  return error
+}
+
+/**
+ * Registers the portable feature-flag contract conformance suite.
+ *
+ * The fixture provides `assay.enabled`, `assay.variant`, and `assay.targeted`; actor
+ * `actor-enabled` matches the targeted rule. Targeting narrows the optional context argument rather
+ * than adding a method, so both directions are checked behaviorally. An unknown flag returns its
+ * supplied default and deliberately produces no taxonomy error.
+ *
+ * @param context Fresh isolated flag drivers and optional cleanup.
+ */
+export function flagsSuite<TDriver extends AssayDriver>(context: SuiteContext<TDriver>): void {
+  describe(`flags conformance: ${context.name}`, () => {
+    assay(context, 'reports a present and stable resolved flags instance', (driver) => {
+      const instance = driver.instance
+      expect(instance.length).toBeGreaterThan(0)
+      expect(driver.instance).toBe(instance)
+    })
+
+    assay(context, 'returns configured flag values with their original types', async (driver) => {
+      expect(await driver.evaluate('assay.enabled', false)).toBe(true)
+      expect(await driver.evaluate('assay.variant', 'control')).toBe('treatment')
+    })
+
+    assay(context, 'returns the supplied default for an unknown flag', async (driver) => {
+      const fallback = { enabled: true, allocation: 0.25, nested: { cohort: 'beta' } }
+      expect(await driver.evaluate('assay.unknown', fallback)).toEqual(fallback)
+    })
+
+    assay(context, 'honors the targeting capability in both directions', async (driver) => {
+      if (driver.capabilities.targeting) {
+        const context = {
+          actorId: 'actor-enabled',
+          organizationId: 'organization-1',
+          attributes: { region: 'us-east', seats: 12, active: true },
+        }
+        const first = await driver.evaluate('assay.targeted', false, context)
+        const second = await driver.evaluate('assay.targeted', false, context)
+        expect(first).toBe(true)
+        expect(second).toBe(first)
+        expect(await driver.evaluate('assay.targeted', false, { actorId: 'actor-disabled' })).toBe(
+          false,
+        )
+      } else {
+        const error = await expectInvalid(() =>
+          driver.evaluate('assay.targeted', false, { actorId: 'actor-enabled' }),
+        )
+        expect(error.metadata.fields?.context).toBeDefined()
+      }
+    })
+  })
+}

package/src/suites/identity.ts

@@ -0,0 +1,293 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  Invalid,
+  Unauthenticated,
+  type IdentityCapabilities,
+  type IdentityDriver,
+  type MagicLinkIdentitySurface,
+  type MfaIdentitySurface,
+  type OAuthIdentitySurface,
+  type OrganizationIdentitySurface,
+  type PasswordIdentitySurface,
+  type RequestCookies,
+} from '@avelonjs/core'
+import { assertCapabilitySurface, captureFailure, type SuiteContext } from '../harness'
+
+type AssayDriver = IdentityDriver<IdentityCapabilities<string>, unknown, unknown, unknown>
+type IdentityFactory<TDriver extends AssayDriver> = (cookies: RequestCookies) => TDriver
+
+class AssayCookies implements RequestCookies {
+  readonly #values = new Map<string, string>()
+  readonly #expired = new Set<string>()
+
+  get size(): number {
+    return this.#values.size
+  }
+
+  get(name: string): string | undefined {
+    return this.#expired.has(name) ? undefined : this.#values.get(name)
+  }
+
+  set(name: string, value: string): void {
+    this.#values.set(name, value)
+    this.#expired.delete(name)
+  }
+
+  delete(name: string): void {
+    this.#values.delete(name)
+    this.#expired.delete(name)
+  }
+
+  expireAll(): void {
+    for (const name of this.#values.keys()) this.#expired.add(name)
+  }
+}
+
+function assay<TDriver extends AssayDriver>(
+  context: SuiteContext<IdentityFactory<TDriver>>,
+  name: string,
+  assertion: (driver: TDriver, cookies: AssayCookies) => Promise<void> | void,
+): void {
+  test(name, async () => {
+    const factory = await context.create()
+    const cookies = new AssayCookies()
+    // A request-scoped dependency stays explicit and testable. Synchronous construction keeps config
+    // resolution deterministic; drivers that need I/O defer it until an operation is called.
+    const driver = factory(cookies)
+    try {
+      await assertion(driver, cookies)
+    } finally {
+      await context.cleanup?.(factory)
+    }
+  })
+}
+
+async function expectUnauthenticated(operation: () => Promise<unknown>): Promise<Unauthenticated> {
+  const error = await captureFailure(operation)
+  expect(error).toBeInstanceOf(Unauthenticated)
+  if (!(error instanceof Unauthenticated)) {
+    throw new Error('Expected Unauthenticated after taxonomy assertion.')
+  }
+  expect(error.code).toBe('UNAUTHENTICATED')
+  return error
+}
+
+async function expectInvalid(operation: () => Promise<unknown>): Promise<Invalid> {
+  const error = await captureFailure(operation)
+  expect(error).toBeInstanceOf(Invalid)
+  if (!(error instanceof Invalid)) throw new Error('Expected Invalid after taxonomy assertion.')
+  expect(error.code).toBe('INVALID')
+  return error
+}
+
+function hasPasswords(driver: AssayDriver): driver is AssayDriver & PasswordIdentitySurface {
+  return driver.capabilities.passwords
+}
+
+function hasMagicLinks(driver: AssayDriver): driver is AssayDriver & MagicLinkIdentitySurface {
+  return driver.capabilities.magicLinks
+}
+
+function hasOAuth(driver: AssayDriver): driver is AssayDriver & OAuthIdentitySurface {
+  return driver.capabilities.oauth
+}
+
+function hasOrganizations(
+  driver: AssayDriver,
+): driver is AssayDriver & OrganizationIdentitySurface {
+  return driver.capabilities.organizations
+}
+
+function hasMfa(driver: AssayDriver): driver is AssayDriver & MfaIdentitySurface<string> {
+  return driver.capabilities.mfa.length > 0
+}
+
+/**
+ * Registers the portable identity contract conformance suite.
+ *
+ * `context.create()` returns the config-time factory, whose pinned signature is
+ * `(cookies: RequestCookies) => TDriver`. Each call to that factory receives one request-scoped
+ * cookie store. Recovery-token and MFA-code providers may supply vendor-issued fixture values;
+ * otherwise password-capable fixtures accept `assay-reset-token` and MFA fixtures accept `123456`.
+ *
+ * @param context Fresh identity factories and optional cleanup.
+ */
+export function identitySuite<TDriver extends AssayDriver>(
+  context: SuiteContext<IdentityFactory<TDriver>>,
+): void {
+  describe(`identity conformance: ${context.name}`, () => {
+    assay(context, 'enforces every identity capability surface in both directions', (driver) => {
+      const surfaces: readonly [string, boolean, readonly string[]][] = [
+        [
+          'passwords',
+          driver.capabilities.passwords,
+          [
+            'register',
+            'signInWithPassword',
+            'sendPasswordReset',
+            'resetPassword',
+            'updatePassword',
+          ],
+        ],
+        ['magicLinks', driver.capabilities.magicLinks, ['sendMagicLink']],
+        ['oauth', driver.capabilities.oauth, ['linkOAuthIdentity']],
+        ['organizations', driver.capabilities.organizations, ['organizations', 'useOrganization']],
+        ['mfa', driver.capabilities.mfa.length > 0, ['challengeMfa', 'verifyMfa']],
+      ]
+      for (const [capability, declared, methods] of surfaces) {
+        assertCapabilitySurface(driver, capability, declared, methods)
+        const unavailable = {
+          capabilities: { [capability]: capability === 'mfa' ? ([] as const) : false },
+        }
+        assertCapabilitySurface(unavailable, capability, false, methods)
+        expect(() =>
+          assertCapabilitySurface(
+            { ...unavailable, [methods[0] ?? 'missing']: () => undefined },
+            capability,
+            false,
+            methods,
+          ),
+        ).toThrow()
+        expect(() =>
+          assertCapabilitySurface(
+            {
+              capabilities: {
+                [capability]: capability === 'mfa' ? (['assay-factor'] as const) : true,
+              },
+            },
+            capability,
+            true,
+            methods,
+          ),
+        ).toThrow()
+      }
+    })
+
+    assay(
+      context,
+      'returns no current actor or session for an anonymous request',
+      async (driver) => {
+        expect(await driver.user()).toBeNull()
+        expect(await driver.session()).toBeNull()
+      },
+    )
+
+    assay(
+      context,
+      'registers and signs in with a password while normalizing bad credentials',
+      async (driver, cookies) => {
+        if (!hasPasswords(driver)) return
+        const registered = await driver.register('actor@example.test', 'initial-password')
+        expect(registered).not.toBeNull()
+        await expectUnauthenticated(() =>
+          driver.signInWithPassword('actor@example.test', 'wrong-password'),
+        )
+        const signedIn = await driver.signInWithPassword('actor@example.test', 'initial-password')
+        // Actor payloads are opaque, so structured equality pins consistency across identity reads
+        // without prescribing fields that real drivers may not share.
+        expect(await driver.user()).toEqual(signedIn)
+        expect(await driver.session()).not.toBeNull()
+        expect(cookies.size).toBeGreaterThan(0)
+      },
+    )
+
+    assay(context, 'signs out the current request and clears its session', async (driver) => {
+      if (!hasPasswords(driver)) return
+      await driver.register('actor@example.test', 'initial-password')
+      await driver.signInWithPassword('actor@example.test', 'initial-password')
+      await driver.signOut()
+      expect(await driver.user()).toBeNull()
+      expect(await driver.session()).toBeNull()
+    })
+
+    assay(
+      context,
+      'rejects operations requiring an absent or expired session as Unauthenticated',
+      async (driver, cookies) => {
+        await expectUnauthenticated(() => driver.signOut())
+        if (!hasPasswords(driver)) return
+        await driver.register('actor@example.test', 'initial-password')
+        await driver.signInWithPassword('actor@example.test', 'initial-password')
+        cookies.expireAll()
+        expect(await driver.user()).toBeNull()
+        expect(await driver.session()).toBeNull()
+        await expectUnauthenticated(() => driver.updatePassword('replacement-password'))
+      },
+    )
+
+    assay(context, 'updates the authenticated actor password', async (driver) => {
+      if (!hasPasswords(driver)) return
+      await driver.register('actor@example.test', 'initial-password')
+      await driver.signInWithPassword('actor@example.test', 'initial-password')
+      await driver.updatePassword('updated-password')
+      await driver.signOut()
+      await expectUnauthenticated(() =>
+        driver.signInWithPassword('actor@example.test', 'initial-password'),
+      )
+      expect(
+        await driver.signInWithPassword('actor@example.test', 'updated-password'),
+      ).not.toBeNull()
+    })
+
+    assay(context, 'resets a password with a vendor recovery token', async (driver) => {
+      if (!hasPasswords(driver)) return
+      await driver.register('actor@example.test', 'initial-password')
+      await driver.sendPasswordReset('actor@example.test')
+      await driver.sendPasswordReset('missing@example.test')
+      const recoveryToken = context.recoveryToken
+        ? await context.recoveryToken('actor@example.test')
+        : 'assay-reset-token'
+      await driver.resetPassword(recoveryToken, 'reset-password')
+      await expectUnauthenticated(() =>
+        driver.signInWithPassword('actor@example.test', 'initial-password'),
+      )
+      expect(await driver.signInWithPassword('actor@example.test', 'reset-password')).not.toBeNull()
+    })
+
+    assay(context, 'sends passwordless magic links when declared', async (driver) => {
+      if (!hasMagicLinks(driver)) return
+      await expect(
+        driver.sendMagicLink('actor@example.test', 'https://app.example.test/complete'),
+      ).resolves.toBeUndefined()
+    })
+
+    assay(context, 'links a completed OAuth identity when declared', async (driver) => {
+      if (!hasPasswords(driver) || !hasOAuth(driver)) return
+      await driver.register('actor@example.test', 'initial-password')
+      await driver.signInWithPassword('actor@example.test', 'initial-password')
+      await expect(
+        driver.linkOAuthIdentity('primary', 'authorization-code'),
+      ).resolves.toBeUndefined()
+    })
+
+    assay(context, 'lists and selects organizations when declared', async (driver) => {
+      if (!hasPasswords(driver) || !hasOrganizations(driver)) return
+      await driver.register('actor@example.test', 'initial-password')
+      await driver.signInWithPassword('actor@example.test', 'initial-password')
+      const organizations = await driver.organizations()
+      expect(organizations.length).toBeGreaterThan(0)
+      const organization = organizations[0]
+      expect(organization).toBeDefined()
+      if (!organization) throw new Error('Expected the organization fixture after assertion.')
+      await expect(driver.useOrganization(organization.id)).resolves.toBeUndefined()
+    })
+
+    assay(
+      context,
+      'challenges only declared MFA factors and verifies their responses',
+      async (driver) => {
+        if (!hasMfa(driver) || !hasPasswords(driver)) return
+        await driver.register('actor@example.test', 'initial-password')
+        await driver.signInWithPassword('actor@example.test', 'initial-password')
+        for (const factor of driver.capabilities.mfa) {
+          const challenge = await driver.challengeMfa(factor)
+          expect(challenge.factor).toBe(factor)
+          expect(challenge.expiresAt.getTime()).toBeGreaterThan(Date.now())
+          const code = context.mfaCode ? await context.mfaCode(challenge.id) : '123456'
+          await expect(driver.verifyMfa(challenge.id, code)).resolves.toBeUndefined()
+        }
+        await expectInvalid(() => driver.challengeMfa('undeclared-factor'))
+      },
+    )
+  })
+}

package/src/suites/index.ts

@@ -0,0 +1,16 @@
+export { aiSuite } from './ai'
+export { cacheSuite } from './cache'
+export { databaseSuite } from './database'
+export { flagsSuite } from './flags'
+export { identitySuite } from './identity'
+export { logsSuite } from './logs'
+export { mailSuite } from './mail'
+export { notificationsSuite } from './notifications'
+export { paymentsSuite } from './payments'
+export { queueSuite } from './queue'
+export { ratelimitSuite } from './ratelimit'
+export { realtimeSuite } from './realtime'
+export { searchSuite } from './search'
+export { socialSuite } from './social'
+export { storageSuite } from './storage'
+export { tokensSuite } from './tokens'

package/src/suites/logs.ts

@@ -0,0 +1,116 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  type LogCapabilities,
+  type LogDriver,
+  type LogLevel,
+  type LogRecord,
+  type TraceLogSurface,
+} from '@avelonjs/core'
+import { assertCapabilitySurface, type SuiteContext } from '../harness'
+
+interface RecordInspectable {
+  readonly records: readonly LogRecord[]
+}
+
+type AssayDriver = LogDriver<LogCapabilities> & Partial<TraceLogSurface> & RecordInspectable
+
+function assay<TDriver extends AssayDriver>(
+  context: SuiteContext<TDriver>,
+  name: string,
+  assertion: (driver: TDriver) => Promise<void> | void,
+): void {
+  test(name, async () => {
+    const driver = await context.create()
+    try {
+      await assertion(driver)
+    } finally {
+      await context.cleanup?.(driver)
+    }
+  })
+}
+
+function hasTraces(driver: AssayDriver): driver is AssayDriver & TraceLogSurface {
+  return driver.capabilities.traces && typeof driver.startSpan === 'function'
+}
+
+/**
+ * Registers the portable structured logging contract conformance suite.
+ *
+ * The context exposes records captured by its test sink so the one-way `write` operation can be
+ * observed. Filtering policy is not part of `LogDriver` and is deliberately not tested here. The
+ * contract also exposes no deterministic failure, so the suite does not invent a taxonomy trigger.
+ *
+ * @param context Fresh isolated log drivers with an observable test sink and optional cleanup.
+ */
+export function logsSuite<TDriver extends AssayDriver>(context: SuiteContext<TDriver>): void {
+  describe(`logs conformance: ${context.name}`, () => {
+    assay(context, 'reports a present and stable resolved logs instance', (driver) => {
+      const instance = driver.instance
+      expect(instance.length).toBeGreaterThan(0)
+      expect(driver.instance).toBe(instance)
+    })
+
+    assay(context, 'enforces the trace capability surface in both directions', (driver) => {
+      assertCapabilitySurface(driver, 'traces', driver.capabilities.traces, ['startSpan'])
+      assertCapabilitySurface({ capabilities: { traces: false } }, 'traces', false, ['startSpan'])
+      expect(() =>
+        assertCapabilitySurface(
+          { capabilities: { traces: false }, startSpan: () => undefined },
+          'traces',
+          false,
+          ['startSpan'],
+        ),
+      ).toThrow()
+      expect(() =>
+        assertCapabilitySurface({ capabilities: { traces: true } }, 'traces', true, ['startSpan']),
+      ).toThrow()
+    })
+
+    assay(context, 'preserves structured log fields without mangling', async (driver) => {
+      const timestamp = new Date('2026-08-03T12:00:00.000Z')
+      const context = {
+        actor: { id: 'actor-1', roles: ['admin', 'editor'] },
+        message: 'Déploiement terminé',
+        default: 'reserved-name',
+        counts: { attempted: 3, failed: 0 },
+      }
+      await driver.write({ level: 'info', message: '公開済み', context, timestamp })
+      await driver.write({ level: 'debug', message: 'Empty context', context: {} })
+
+      expect(driver.records[0]).toEqual({
+        level: 'info',
+        message: '公開済み',
+        context,
+        timestamp,
+      })
+      expect(driver.records[1]?.context).toEqual({})
+    })
+
+    assay(context, 'retains every declared log level on the record', async (driver) => {
+      const levels: readonly LogLevel[] = ['debug', 'info', 'warning', 'error']
+      for (const level of levels) await driver.write({ level, message: `${level} message` })
+      expect(driver.records.map((record) => record.level)).toEqual([...levels])
+    })
+
+    assay(context, 'defaults an omitted record timestamp to the current time', async (driver) => {
+      const before = Date.now()
+      await driver.write({ level: 'info', message: 'Timestamped by the driver' })
+      const after = Date.now()
+      const timestamp = driver.records[0]?.timestamp
+      expect(timestamp).toBeInstanceOf(Date)
+      expect(timestamp?.getTime()).toBeGreaterThanOrEqual(before)
+      expect(timestamp?.getTime()).toBeLessThanOrEqual(after)
+    })
+
+    assay(context, 'starts and completes trace spans when declared', (driver) => {
+      if (!hasTraces(driver)) return
+      const span = driver.startSpan('publish-post', { postId: 'post-1', attempts: 2 })
+      expect(span.traceId.length).toBeGreaterThan(0)
+      expect(span.spanId.length).toBeGreaterThan(0)
+      const error = new Error('trace event')
+      expect(() => span.attribute('published', true)).not.toThrow()
+      expect(() => span.recordError(error)).not.toThrow()
+      expect(() => span.end()).not.toThrow()
+    })
+  })
+}

package/src/suites/mail.ts

@@ -0,0 +1,160 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  Invalid,
+  type MailCapabilities,
+  type MailDriver,
+  type MailMessage,
+  type TemplateMailSurface,
+} from '@avelonjs/core'
+import { assertCapabilitySurface, captureFailure, type SuiteContext } from '../harness'
+
+type AssayDriver = MailDriver<MailCapabilities> & Partial<TemplateMailSurface>
+
+interface SentMailInspectable {
+  readonly sent: readonly MailMessage[]
+}
+
+function assay<TDriver extends AssayDriver>(
+  context: SuiteContext<TDriver>,
+  name: string,
+  assertion: (driver: TDriver) => Promise<void> | void,
+): void {
+  test(name, async () => {
+    const driver = await context.create()
+    try {
+      await assertion(driver)
+    } finally {
+      await context.cleanup?.(driver)
+    }
+  })
+}
+
+function hasTemplates(driver: AssayDriver): driver is AssayDriver & TemplateMailSurface {
+  return driver.capabilities.templates && typeof driver.sendTemplate === 'function'
+}
+
+function hasSentInspection(driver: object): driver is SentMailInspectable {
+  return 'sent' in driver && Array.isArray(driver.sent)
+}
+
+async function expectInvalid(operation: () => Promise<unknown>): Promise<Invalid> {
+  const error = await captureFailure(operation)
+  expect(error).toBeInstanceOf(Invalid)
+  if (!(error instanceof Invalid)) throw new Error('Expected Invalid after taxonomy assertion.')
+  expect(error.code).toBe('INVALID')
+  return error
+}
+
+/**
+ * Registers the portable mail contract conformance suite.
+ *
+ * The context supplies one already-resolved mailer. Named-mailer resolution and unknown-name
+ * rejection belong to configuration and the mail facade; this suite verifies only the driver's
+ * stable instance identity. The frozen contract defines no deterministic trigger for provider
+ * unavailability or rate limiting, so this suite does not invent one.
+ *
+ * @param context Fresh isolated mail drivers and optional cleanup.
+ */
+export function mailSuite<TDriver extends AssayDriver>(context: SuiteContext<TDriver>): void {
+  const sender = context.mailSender ?? 'sender@example.test'
+  const recipients = context.mailRecipients ?? {
+    to: ['first@example.test', 'second@example.test'],
+    replyTo: ['replies@example.test', 'support@example.test'],
+    cc: 'copy@example.test',
+    bcc: 'audit@example.test',
+    configured: 'recipient@example.test',
+  }
+
+  describe(`mail conformance: ${context.name}`, () => {
+    assay(context, 'reports a present and stable resolved mailer instance', (driver) => {
+      const instance = driver.instance
+      expect(instance.length).toBeGreaterThan(0)
+      expect(driver.instance).toBe(instance)
+    })
+
+    assay(context, 'enforces every mail capability surface in both directions', (driver) => {
+      assertCapabilitySurface(driver, 'templates', driver.capabilities.templates, ['sendTemplate'])
+      const unavailable = { capabilities: { templates: false } as const }
+      assertCapabilitySurface(unavailable, 'templates', false, ['sendTemplate'])
+      expect(() =>
+        assertCapabilitySurface(
+          { ...unavailable, sendTemplate: () => undefined },
+          'templates',
+          false,
+          ['sendTemplate'],
+        ),
+      ).toThrow()
+      expect(() =>
+        assertCapabilitySurface({ capabilities: { templates: true } as const }, 'templates', true, [
+          'sendTemplate',
+        ]),
+      ).toThrow()
+    })
+
+    assay(
+      context,
+      'sends multiple recipients with reply-to, cc, bcc, and attachments intact',
+      async (driver) => {
+        const attachment = new Uint8Array([0, 255, 4])
+        const receipt = await driver.send({
+          to: recipients.to,
+          from: sender,
+          replyTo: recipients.replyTo,
+          cc: [recipients.cc],
+          bcc: [recipients.bcc],
+          subject: 'Quarterly report',
+          text: 'The report is attached.',
+          html: '<p>The report is attached.</p>',
+          attachments: [
+            {
+              filename: 'report.bin',
+              content: attachment,
+              contentType: 'application/octet-stream',
+            },
+          ],
+        })
+
+        // Accepted means every envelope recipient, including cc and bcc but excluding reply-to.
+        expect(receipt.accepted).toEqual([...recipients.to, recipients.cc, recipients.bcc])
+        expect(receipt.id.length).toBeGreaterThan(0)
+
+        if (hasSentInspection(driver)) {
+          expect(driver.sent).toHaveLength(1)
+          expect(driver.sent[0]).toMatchObject({
+            to: recipients.to,
+            from: sender,
+            replyTo: recipients.replyTo,
+            cc: [recipients.cc],
+            bcc: [recipients.bcc],
+          })
+          expect(driver.sent[0]?.attachments?.[0]?.content).toEqual(attachment)
+        }
+      },
+    )
+
+    assay(context, 'uses the configured sender when from is omitted', async (driver) => {
+      await driver.send({
+        to: recipients.configured,
+        subject: 'Configured sender',
+        text: 'Sender defaults are instance-owned.',
+      })
+      if (hasSentInspection(driver)) expect(driver.sent[0]?.from).toBe('mailer@example.test')
+    })
+
+    assay(context, 'normalizes malformed recipient addresses to Invalid', async (driver) => {
+      const error = await expectInvalid(() =>
+        driver.send({ to: 'not-an-address', subject: 'Invalid recipient', text: 'Not delivered.' }),
+      )
+      expect(error.metadata.fields?.to?.join(' ')).toContain('not-an-address')
+    })
+
+    assay(context, 'sends hosted templates only when declared', async (driver) => {
+      if (!hasTemplates(driver)) return
+      const receipt = await driver.sendTemplate('welcome-message', recipients.to, {
+        actorName: 'Morgan',
+      })
+      expect(receipt.accepted).toEqual(recipients.to)
+      expect(receipt.id.length).toBeGreaterThan(0)
+    })
+  })
+}