velocious 1.0.595 → 1.0.597

package/build/database/drivers/base.js

@@ -150,6 +150,65 @@ const SQL_PREVIEW_SCAN_LIMIT = 4096
 /** Maximum characters inspected when deciding whether a statement invalidates schema metadata. */
 const SCHEMA_INVALIDATION_SCAN_LIMIT = 8192
 
+/**
+ * Builds a non-reversible, stable SQL fingerprint without retaining SQL text. Literal spelling is
+ * normalized first so the same statement shape produces the same fingerprint across values.
+ * @param {string} sql - SQL to fingerprint.
+ * @returns {string} - Bounded fingerprint.
+ */
+function sqlFingerprint(sql) {
+  let fingerprintInput = ""
+
+  for (let index = 0; index < sql.length;) {
+    const character = sql[index]
+    const nextCharacter = sql[index + 1]
+
+    if (character == "'" || character == '"') {
+      const quote = character
+      fingerprintInput += "?"
+      index++
+
+      while (index < sql.length) {
+        if (sql[index] == "\\") {
+          index += 2
+        } else if (sql[index] == quote && sql[index + 1] == quote) {
+          index += 2
+        } else if (sql[index] == quote) {
+          index++
+          break
+        } else {
+          index++
+        }
+      }
+    } else if (character == "/" && nextCharacter == "*") {
+      const commentEnd = sql.indexOf("*/", index + 2)
+      fingerprintInput += " "
+      index = commentEnd == -1 ? sql.length : commentEnd + 2
+    } else if ((character == "-" && nextCharacter == "-") || character == "#") {
+      const lineEnd = sql.indexOf("\n", index + 1)
+      fingerprintInput += " "
+      index = lineEnd == -1 ? sql.length : lineEnd + 1
+    } else {
+      fingerprintInput += character
+      index++
+    }
+  }
+
+  const normalized = fingerprintInput
+    .replace(/\b(?:0x[0-9a-f]+|\d+(?:\.\d+)?(?:e[+-]?\d+)?)\b/gi, "?")
+    .replace(/\s+/g, " ")
+    .trim()
+    .toLowerCase()
+  let hash = 0xcbf29ce484222325n
+
+  for (let index = 0; index < normalized.length; index++) {
+    hash ^= BigInt(normalized.charCodeAt(index))
+    hash = BigInt.asUintN(64, hash * 0x100000001b3n)
+  }
+
+  return `fnv1a64:${hash.toString(16).padStart(16, "0")}`
+}
+
 /**
  * Marks a callback failure that happened after the owning transaction was durably committed.
  * The public transaction boundary unwraps it before deadlock classification.
@@ -215,6 +274,8 @@ export default class VelociousDatabaseDriversBase {
    * Active query.
    * @type {ActiveQueryState | null} */
   _activeQuery = null
+  /** @type {WeakMap<Error, {sqlFingerprint: string, sqlOperation: string}>} */
+  _failedQueryDiagnostics = new WeakMap()
   /** @type {Map<string, number>} */
   _heldAdvisoryLocks = new Map()
   /**
@@ -1248,10 +1309,13 @@ export default class VelociousDatabaseDriversBase {
         return await this._runTransactionAttempt(callback, options)
       } catch (error) {
         if (error instanceof VelociousDatabaseAfterCommitCallbackError) throw error.callbackError
+        if (!(error instanceof Error)) throw error
 
-        const retryInfo = error instanceof Error ? this.retryableDatabaseError(error) : {retry: false, reconnect: false}
+        const retryInfo = this.retryableDatabaseError(error)
 
         if (retryInfo.deadlock && attempt < maxAttempts && this._transactionsCount == 0) {
+          this._reportDeadlockRetryDiagnostic({attempt, error, maxAttempts})
+
           // An explicitly-configured base wins so the tuning knob is effective even on drivers
           // whose classifier supplies its own `waitMs` (MySQL/MariaDB return a fixed 50ms for
           // deadlocks); otherwise honor that classifier hint, then fall back to 50ms.
@@ -1286,6 +1350,71 @@ export default class VelociousDatabaseDriversBase {
     await wait(ms)
   }
 
+  /**
+   * Starts best-effort deadlock diagnostics without joining the retry control flow. Subclasses may
+   * add bounded driver-specific context; capture and event-listener failures cannot affect retry.
+   * @param {{attempt: number, error: Error, maxAttempts: number}} args - Retry metadata.
+   * @returns {void}
+   */
+  _reportDeadlockRetryDiagnostic({attempt, error, maxAttempts}) {
+    const queryDiagnostic = this._failedQueryDiagnostics.get(error)
+
+    void this._deadlockDiagnosticContext()
+      .then((driverContext) => {
+        const context = {
+          attempt,
+          driverType: this.getType(),
+          maxAttempts,
+          stage: "database-deadlock-retry",
+          willRetry: true,
+          ...queryDiagnostic,
+          ...driverContext
+        }
+        const payload = {
+          context,
+          error: new Error("Database transaction deadlock will be retried")
+        }
+        const errorEvents = this.configuration.getErrorEvents()
+
+        try {
+          errorEvents.emit("database-deadlock-retry", payload)
+        } catch (eventError) {
+          this.logger.warn("Database deadlock retry diagnostic listener failed", {error: eventError})
+        }
+
+        try {
+          errorEvents.emit("all-error", {...payload, errorType: "database-deadlock-retry"})
+        } catch (eventError) {
+          this.logger.warn("Database deadlock retry all-error listener failed", {error: eventError})
+        }
+      })
+      .catch((diagnosticError) => {
+        const normalizedError = diagnosticError instanceof Error
+          ? diagnosticError
+          : new Error("Database deadlock retry diagnostic failed", {cause: diagnosticError})
+        const payload = {
+          context: {stage: "database-deadlock-retry-diagnostic"},
+          error: normalizedError
+        }
+
+        try {
+          const errorEvents = this.configuration.getErrorEvents()
+          errorEvents.emit("framework-error", payload)
+          errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
+        } catch (reportingError) {
+          this.logger.warn("Database deadlock retry diagnostic pipeline failed", {error: normalizedError, reportingError})
+        }
+      })
+  }
+
+  /**
+   * Builds driver-specific deadlock context. The base driver has no server diagnostic source.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} - Safe context fields.
+   */
+  async _deadlockDiagnosticContext() {
+    return {}
+  }
+
   /**
    * Runs a single transaction attempt: starts a transaction (or a savepoint when nested), runs
    * `callback`, and commits — rolling back on error. {@link transaction} wraps this with deadlock
@@ -1587,6 +1716,11 @@ export default class VelociousDatabaseDriversBase {
       } catch (error) {
         if (!(error instanceof Error)) throw error
 
+        this._failedQueryDiagnostics.set(error, {
+          sqlFingerprint: sqlFingerprint(sql),
+          sqlOperation: sql.trim().split(/\s+/, 1)[0]?.toUpperCase() || "UNKNOWN"
+        })
+
         // A deliberately-aborted query must never be silently re-run — its
         // connection was destroyed on purpose, so treat it as terminal.
         if (error instanceof QueryAbortedError) throw error

package/build/database/drivers/mysql/index.js

@@ -31,6 +31,7 @@ import Update from "./sql/update.js"
  * realistic critical section) instead.
  */
 const MYSQL_INDEFINITE_LOCK_TIMEOUT_SECONDS = 60 * 60 * 24 * 365
+const INNODB_DEADLOCK_CAPTURE_TIMEOUT_MS = 250
 
 export default class VelociousDatabaseDriversMysql extends Base{
   /** @type {import("mysql").Pool | undefined} */
@@ -392,6 +393,97 @@ export default class VelociousDatabaseDriversMysql extends Base{
     }
   }
 
+  /**
+   * Adds a redacted, bounded excerpt from MySQL's latest InnoDB deadlock report. Capture uses a
+   * separate short-lived connection so it cannot queue ahead of rollback or the next retry on this
+   * driver's single-connection pool.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} - Safe diagnostic context.
+   */
+  async _deadlockDiagnosticContext() {
+    try {
+      const status = await this._captureInnodbDeadlockStatus()
+
+      return {
+        innodbDeadlockSummary: this._innodbDeadlockSummary(status),
+        statusCapture: "captured"
+      }
+    } catch {
+      return {statusCapture: "failed"}
+    }
+  }
+
+  /**
+   * Captures SHOW ENGINE INNODB STATUS on a bounded throwaway connection.
+   * @returns {Promise<string>} - Raw server status, retained only inside the redaction path.
+   */
+  async _captureInnodbDeadlockStatus() {
+    const poolWithConfig = /** @type {{config?: {connectionConfig?: ReturnType<typeof JSON.parse>}} | undefined} */ (this.pool)
+    const connectionConfig = poolWithConfig?.config?.connectionConfig
+    const captureConfig = connectionConfig || this.connectArgs()
+
+    return await new Promise((resolve, reject) => {
+      /** @type {import("mysql").Connection | undefined} */
+      let connection
+      let settled = false
+      /**
+       * Finishes the status capture once and destroys its temporary connection.
+       * @param {Error | undefined} error - Capture error, when present.
+       * @param {string} [status] - Captured status.
+       * @returns {void}
+       */
+      const finish = (error, status = "") => {
+        if (settled) return
+        settled = true
+        clearTimeout(timeout)
+        if (connection) connection.destroy()
+        if (error) reject(error)
+        else resolve(status)
+      }
+      const timeout = setTimeout(() => finish(new Error("InnoDB status capture timed out")), INNODB_DEADLOCK_CAPTURE_TIMEOUT_MS)
+
+      try {
+        connection = mysql.createConnection(captureConfig)
+        connection.on("error", (error) => finish(error))
+        connection.query("SHOW ENGINE INNODB STATUS", (error, rows) => {
+          if (error) {
+            finish(error)
+            return
+          }
+
+          const firstRow = Array.isArray(rows) ? rows[0] : undefined
+          const status = firstRow && typeof firstRow.Status == "string" ? firstRow.Status : ""
+
+          finish(undefined, status)
+        })
+      } catch (error) {
+        finish(error instanceof Error ? error : new Error("InnoDB status capture failed"))
+      }
+    })
+  }
+
+  /**
+   * Extracts only fixed-format deadlock counters. The server report contains raw SQL, identifiers,
+   * and physical record data, so no source text is ever included in an application diagnostic.
+   * @param {string} status - SHOW ENGINE INNODB STATUS text.
+   * @returns {{transactions: number, victimTransaction: number | null}} - Structural deadlock summary.
+   */
+  _innodbDeadlockSummary(status) {
+    const deadlockStart = status.indexOf("LATEST DETECTED DEADLOCK")
+    const candidate = deadlockStart >= 0 ? status.slice(deadlockStart) : status
+    let transactions = 0
+    /** @type {number | null} */
+    let victimTransaction = null
+
+    for (const line of candidate.split(/\r?\n/)) {
+      const trimmed = line.trim()
+      if (/^\*\*\* \(\d+\) TRANSACTION:$/.test(trimmed)) transactions++
+      const victimMatch = /^\*\*\* WE ROLL BACK TRANSACTION \((\d+)\)$/.exec(trimmed)
+      if (victimMatch) victimTransaction = Number(victimMatch[1])
+    }
+
+    return {transactions, victimTransaction}
+  }
+
   /**
    * Runs query actual.
    * @param {string} sql - SQL string.

package/build/database/drivers/sqlite/base.js

@@ -356,13 +356,13 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
    * @returns {import("../base.js").RetryableDatabaseErrorResult} - Retry info.
    */
   retryableDatabaseError(error) {
+    const databaseLocked = Boolean(error.message?.includes("database is locked"))
     const shouldRetry = (
       error.message?.startsWith("attempt to write a readonly database") ||
-      error.message?.startsWith("database is locked") ||
-      error.message?.includes("→ Caused by: Error code : database is locked")
+      databaseLocked
     )
 
-    return {retry: shouldRetry, reconnect: false}
+    return {deadlock: databaseLocked, retry: shouldRetry, reconnect: false}
   }
 
   /**

package/build/database/tenants/migration-pending-inspector.js

@@ -0,0 +1,77 @@
+// @ts-check
+
+import MigrationsLedger from "../migrations-ledger.js"
+import TenantIterator from "../../tenants/tenant-iterator.js"
+import restArgsError from "../../utils/rest-args-error.js"
+
+export default class TenantMigrationPendingInspector {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("../../configuration.js").default} args.configuration - Configuration instance.
+   * @param {string} args.identifier - Tenant database identifier.
+   * @param {number[]} args.migrationVersions - Applicable migration versions.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.tenants - Existing tenant descriptors.
+   */
+  constructor({configuration, identifier, migrationVersions, tenants, ...restArgs}) {
+    restArgsError(restArgs)
+
+    this.configuration = configuration
+    this.identifier = identifier
+    this.migrationVersions = migrationVersions.map((version) => `${version}`)
+    this.tenants = tenants
+  }
+
+  /**
+   * Reads every existing tenant ledger and reports aggregate pending state.
+   * @returns {Promise<{hasPendingMigrations: boolean, identifier: string, migrationCount: number, pendingTenantCount: number, tenantCount: number}>} - Deploy preflight result.
+   */
+  async inspect() {
+    let pendingTenantCount = 0
+
+    for (const tenant of this.tenants) {
+      if (await this.tenantHasPendingMigrations(tenant)) pendingTenantCount++
+    }
+
+    return {
+      hasPendingMigrations: pendingTenantCount > 0,
+      identifier: this.identifier,
+      migrationCount: this.migrationVersions.length,
+      pendingTenantCount,
+      tenantCount: this.tenants.length
+    }
+  }
+
+  /**
+   * Reads one tenant's existing migration ledger without preparing or changing it.
+   * @param {ReturnType<typeof JSON.parse>} tenant - Tenant descriptor.
+   * @returns {Promise<boolean>} - Whether the tenant has an applicable pending migration.
+   */
+  async tenantHasPendingMigrations(tenant) {
+    return await this.configuration.runWithTenant(tenant, async () => {
+      const tenantLabel = TenantIterator.tenantLabel(tenant)
+
+      if (!this.configuration.isDatabaseIdentifierActive(this.identifier)) {
+        throw new Error(`Tenant database identifier ${this.identifier} is inactive for tenant: ${tenantLabel}`)
+      }
+
+      try {
+        return await this.configuration.ensureConnections({
+          databaseIdentifiers: [this.identifier],
+          name: `Tenant migration pending preflight: ${this.identifier}`
+        }, async (dbs) => {
+          const db = dbs[this.identifier]
+
+          if (!db) throw new Error(`Tenant database identifier ${this.identifier} did not open a connection`)
+          if (!await MigrationsLedger.tableExists(db)) throw new Error(`${MigrationsLedger.tableName()} ledger does not exist`)
+
+          const appliedVersions = new Set(await MigrationsLedger.appliedVersions(db))
+
+          return this.migrationVersions.some((version) => !appliedVersions.has(version))
+        })
+      } catch (error) {
+        throw new Error(`Could not read ${MigrationsLedger.tableName()} for tenant ${tenantLabel}`, {cause: error})
+      }
+    })
+  }
+}

package/build/environment-handlers/base.js

@@ -19,6 +19,14 @@ import {validateTimeZone} from "../time-zone.js"
  */
 
 export default class VelociousEnvironmentHandlerBase {
+  /**
+   * Resolves the configured database pool type for the current runtime context.
+   * Browser and ordinary server contexts retain the application configuration.
+   * @param {{configuredPoolType: typeof import("../database/pool/base.js").default, databaseIdentifier: string}} args - Configured pool and logical database identifier.
+   * @returns {typeof import("../database/pool/base.js").default} - Pool type for this context.
+   */
+  resolveTestSharedTransactionPoolType({configuredPoolType}) { return configuredPoolType }
+
   /**
    * Node test runtimes may replace a physical child connection with a broker
    * proxy. Other environments never participate in this test-only protocol.

package/build/environment-handlers/node.js

@@ -32,6 +32,7 @@ import path from "path"
 import {AsyncLocalStorage as NodeAsyncLocalStorage} from "node:async_hooks"
 import {timingSafeEqual} from "node:crypto"
 import requireContext from "require-context"
+import AsyncTrackedMultiConnectionPool from "../database/pool/async-tracked-multi-connection.js"
 import InitializerFromRequireContext from "../database/initializer-from-require-context.js"
 import toImportSpecifier from "../utils/to-import-specifier.js"
 import {validateTimeZone} from "../time-zone.js"
@@ -64,6 +65,19 @@ function pathWithinAllowedPrefixes(filePath, allowedPathPrefixes) {
 }
 
 export default class VelociousEnvironmentHandlerNode extends Base{
+  /**
+   * Gives concurrent shared-transaction child jobs independent proxy sessions.
+   * A configured single-connection pool shares mutable transaction state between
+   * async jobs, while the broker requires one root-transaction lease per socket.
+   * @param {{configuredPoolType: typeof import("../database/pool/base.js").default, databaseIdentifier: string}} args - Configured pool and logical database identifier.
+   * @returns {typeof import("../database/pool/base.js").default} - Pool type for this context.
+   */
+  resolveTestSharedTransactionPoolType({configuredPoolType, databaseIdentifier}) {
+    if (!sharedTransactionBrokerConfig(databaseIdentifier)) return configuredPoolType
+
+    return AsyncTrackedMultiConnectionPool
+  }
+
   /**
    * Creates a test-only child proxy when TestRunner supplied an active broker.
    * @param {{DriverClass: typeof import("../database/drivers/base.js").default, config: import("../configuration-types.js").DatabaseConfigurationType, configuration: import("../configuration.js").default, databaseIdentifier: string}} args - Connection details.

package/build/mailer/backends/resend-smtp.js

@@ -0,0 +1,121 @@
+// @ts-check
+
+import SmtpMailerBackend from "./smtp.js"
+import VelociousError from "../../velocious-error.js"
+import {deliveryOperationFromPayload} from "../delivery-operation.js"
+
+const PROVIDER_KIND = "resend-smtp"
+const RETENTION_MS = 24 * 60 * 60 * 1000
+const IDEMPOTENCY_HEADER = "Resend-Idempotency-Key"
+
+/**
+ * Checks whether a value contains an SMTP header control character.
+ * @param {string} value - Header value.
+ * @returns {boolean} - Whether a control character is present.
+ */
+function containsHeaderValueControlCharacter(value) {
+  for (const character of value) {
+    const codePoint = character.charCodeAt(0)
+
+    if (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f)) return true
+  }
+
+  return false
+}
+
+/**
+ * Keeps the provider-owned operation header out of caller payloads.
+ * @param {import("../index.js").MailerDeliveryPayload} payload - Mail payload.
+ * @returns {void}
+ */
+function rejectReservedHeaderOverride(payload) {
+  if (Object.keys(payload.headers || {}).some((name) => name.toLowerCase() === IDEMPOTENCY_HEADER.toLowerCase())) {
+    throw VelociousError.safe(`Reserved mail header ${IDEMPOTENCY_HEADER} is owned by ResendSmtpMailerBackend required delivery operations.`, {
+      code: "mail-delivery-idempotency-header-reserved"
+    })
+  }
+}
+
+/**
+ * Resend SMTP transport with Resend's documented 24-hour idempotency header.
+ */
+export default class ResendSmtpMailerBackend extends SmtpMailerBackend {
+  /**
+   * Resolves the SMTP sender before it becomes part of the immutable digest.
+   * @param {object} args - Preparation input.
+   * @param {import("../index.js").MailerDeliveryPayload} args.payload - Rendered payload.
+   * @returns {import("../index.js").MailerDeliveryPayload} - Provider-ready payload.
+   */
+  prepareDeliveryOperationPayload({payload}) {
+    const from = payload.from || this.defaultFrom
+
+    if (!from) {
+      throw VelociousError.safe("Required Resend mail delivery needs a from address.", {
+        code: "mail-delivery-from-missing"
+      })
+    }
+
+    return {...payload, from}
+  }
+
+  /**
+   * Advertises the provider-specific guarantee used by required operations.
+   * @returns {import("../index.js").MailerDeliveryIdempotencyCapability} - Capability.
+   */
+  deliveryIdempotencyCapability() {
+    return {providerKind: PROVIDER_KIND, retentionMs: RETENTION_MS}
+  }
+
+  /**
+   * Validates Resend's documented length and SMTP header-value safety contract.
+   * @param {object} args - Validation input.
+   * @param {import("../index.js").MailerDeliveryOperationRequest | import("../index.js").MailerDeliveryOperation} args.deliveryOperation - Operation.
+   * @param {import("../index.js").MailerDeliveryPayload} args.payload - Rendered or persisted mail payload.
+   * @returns {void}
+   */
+  validateDeliveryOperation({deliveryOperation, payload}) {
+    if (
+      typeof deliveryOperation.id !== "string" ||
+      deliveryOperation.id.length < 1 ||
+      deliveryOperation.id.length > 256 ||
+      containsHeaderValueControlCharacter(deliveryOperation.id)
+    ) {
+      throw VelociousError.safe("Resend idempotency keys must contain between 1 and 256 characters without control characters.", {
+        code: "mail-delivery-idempotency-key-invalid"
+      })
+    }
+
+    rejectReservedHeaderOverride(payload)
+  }
+
+  /**
+   * Injects the framework-owned Resend operation header before generic SMTP serialization.
+   * @param {object} args - Delivery args.
+   * @param {import("../index.js").MailerDeliveryPayload} args.payload - Mail payload.
+   * @param {import("../../configuration.js").default} [args.configuration] - Active configuration.
+   * @returns {Promise<void>} - Resolves when accepted and shut down.
+   */
+  async deliver({payload, configuration}) {
+    const headers = payload.headers || {}
+
+    if (payload.deliveryOperation) {
+      this.validateDeliveryOperation({deliveryOperation: payload.deliveryOperation, payload})
+    } else {
+      rejectReservedHeaderOverride(payload)
+    }
+    const operation = deliveryOperationFromPayload(payload)
+
+    if (!operation) {
+      await super.deliver({payload, configuration})
+      return
+    }
+
+    await super.deliver({
+      configuration,
+      payload: {
+        ...payload,
+        headers: {...headers, [IDEMPOTENCY_HEADER]: operation.id}
+      }
+    })
+  }
+}

package/build/mailer/base.js

@@ -3,9 +3,16 @@
 import ejs from "ejs"
 import {incorporate} from "incorporator"
 import * as inflection from "inflection"
+import BackgroundJobsClient from "../background-jobs/client.js"
 import configurationResolver from "../configuration-resolver.js"
 import restArgsError from "../utils/rest-args-error.js"
 import MailerDelivery from "./delivery.js"
+import MailerDeliveryOperationStore from "./delivery-operation-store.js"
+import {
+  deliveryOperationFromPayload,
+  prepareRequiredDeliveryPayload,
+  requireDeliveryIdempotencyCapability
+} from "./delivery-operation.js"
 
 /**
  * Deliveries store.
@@ -66,16 +73,6 @@ function inferActionName(mailerClass, stack) {
   return actionName
 }
 
-/**
- * Runs is testing environment.
- * @returns {Promise<boolean>} - Whether the current environment is test.
- */
-async function isTestingEnvironment() {
-  const configuration = await configurationResolver()
-
-  return configuration.getEnvironment() === "test"
-}
-
 /**
  * Base mailer with view rendering and delivery helpers.
  */
@@ -241,10 +238,13 @@ export class VelociousMailerBase {
   /**
    * Runs enqueue payload.
    * @param {import("./index.js").MailerDeliveryPayload} payload - Mail delivery payload.
+   * @param {import("./index.js").MailerDeliveryLaterOptions} [options] - Delivery execution options.
    * @returns {Promise<string | import("./index.js").MailerDeliveryPayload | null>} - Job id or payload in test mode.
    */
-  async _enqueuePayload(payload) {
-    return await enqueuePayload(payload)
+  async _enqueuePayload(payload, options) {
+    const configuration = await this._getConfiguration()
+
+    return await enqueuePayload(payload, {...options, configuration})
   }
 }
 
@@ -287,14 +287,22 @@ export function getDeliveryHandler() {
  * @returns {Promise<import("./index.js").MailerDeliveryPayload | ReturnType<typeof JSON.parse>>} - Handler result.
  */
 export async function deliverPayload(payload) {
-  if (await isTestingEnvironment()) {
+  const configuration = await configurationResolver()
+  const backend = configuration.getMailerBackend()
+  const deliveryOperation = deliveryOperationFromPayload(payload)
+
+  if (deliveryOperation) {
+    const capability = requireDeliveryIdempotencyCapability({backend, deliveryOperation, payload})
+    const operationStore = new MailerDeliveryOperationStore({configuration})
+
+    await operationStore.beginAttempt({capability, payload})
+  }
+
+  if (configuration.getEnvironment() === "test") {
     deliveriesStore.push(payload)
     return payload
   }
 
-  const configuration = await configurationResolver()
-  const backend = configuration.getMailerBackend()
-
   if (backend?.deliver) {
     return await backend.deliver({payload, configuration})
   }
@@ -311,15 +319,37 @@ export async function deliverPayload(payload) {
 /**
  * Runs the enqueuePayload helper.
  * @param {import("./index.js").MailerDeliveryPayload} payload - Mail delivery payload.
+ * @param {object} [options] - Enqueue options.
+ * @param {import("../configuration.js").default} [options.configuration] - Owning configuration.
+ * @param {import("./index.js").MailerDeliveryOperationRequest} [options.deliveryOperation] - Required provider-backed operation.
  * @returns {Promise<string | import("./index.js").MailerDeliveryPayload | null>} - Job id or payload in test mode.
  */
-export async function enqueuePayload(payload) {
-  if (await isTestingEnvironment()) {
-    deliveriesStore.push(payload)
-    return payload
+export async function enqueuePayload(payload, {configuration: suppliedConfiguration, deliveryOperation} = {}) {
+  const configuration = suppliedConfiguration || await configurationResolver()
+  let persistedPayload = payload
+
+  if (deliveryOperation) {
+    const backend = configuration.getMailerBackend()
+    const operationPayload = typeof backend?.prepareDeliveryOperationPayload === "function"
+      ? backend.prepareDeliveryOperationPayload({payload})
+      : payload
+    const capability = requireDeliveryIdempotencyCapability({backend, deliveryOperation, payload: operationPayload})
+
+    persistedPayload = prepareRequiredDeliveryPayload({capability, deliveryOperation, payload: operationPayload})
   }
 
-  const {default: mailDeliveryJob} = await import("../jobs/mail-delivery.js")
+  if (configuration.getEnvironment() === "test") {
+    deliveriesStore.push(persistedPayload)
+    return persistedPayload
+  }
 
-  return await mailDeliveryJob.performLater(payload)
+  const {default: mailDeliveryJob} = await import("../jobs/mail-delivery.js")
+  const client = new BackgroundJobsClient({configuration})
+  const jobOptions = mailDeliveryJob._withQueue(deliveryOperation ? {idempotencyKey: deliveryOperation.id} : undefined)
+
+  return await client.enqueue({
+    args: [persistedPayload],
+    jobName: mailDeliveryJob.jobName(),
+    options: jobOptions
+  })
 }