velocious 1.0.596 → 1.0.598

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
+  })
 }

package/build/mailer/delivery-operation-store.js

@@ -0,0 +1,152 @@
+// @ts-check
+
+import BackgroundJobsStore from "../background-jobs/store.js"
+import VelociousError from "../velocious-error.js"
+import {
+  MAIL_DELIVERY_OPERATIONS_TABLE,
+  mailDeliveryOperationKey,
+  validateAttemptPayload
+} from "./delivery-operation.js"
+
+/**
+ * Durable first-attempt and retention guard for required mail operations.
+ */
+export default class MailerDeliveryOperationStore {
+  /**
+   * Creates a durable mail-operation state guard.
+   * @param {object} args - Store input.
+   * @param {import("../configuration.js").default} args.configuration - Active configuration.
+   * @param {() => number} [args.clock] - Explicit clock dependency.
+   */
+  constructor({configuration, clock = () => Date.now()}) {
+    this.backgroundJobsStore = new BackgroundJobsStore({configuration})
+    this.clock = clock
+    this.configuration = configuration
+  }
+
+  /**
+   * Atomically starts the provider retention clock once and rejects expired attempts.
+   * @param {object} args - Attempt input.
+   * @param {import("./index.js").MailerDeliveryIdempotencyCapability} args.capability - Current backend capability.
+   * @param {import("./index.js").MailerDeliveryPayload} args.payload - Persisted payload.
+   * @returns {Promise<{expiresAtMs: number, firstAttemptStartedAtMs: number}>} - Attempt window.
+   */
+  async beginAttempt({capability, payload}) {
+    const operation = validateAttemptPayload({capability, payload})
+    const nowMs = this.clock()
+
+    if (!Number.isSafeInteger(nowMs) || nowMs < 0) throw new Error("Mailer delivery operation clock must return a non-negative safe integer")
+
+    const databaseIdentifier = this.backgroundJobsStore.getDatabaseIdentifier()
+
+    return await this.configuration.ensureConnections({
+      databaseIdentifiers: [databaseIdentifier],
+      name: "Mailer delivery operation attempt"
+    }, async (dbs) => {
+      const db = dbs[databaseIdentifier]
+
+      if (db.insideTransaction()) {
+        throw VelociousError.safe("Required mail delivery cannot start inside an existing database transaction.", {
+          code: "mail-delivery-idempotency-transaction-active"
+        })
+      }
+
+      await this.backgroundJobsStore.ensureSchema(db)
+
+      return await db.transaction(async () => {
+        const operationKey = mailDeliveryOperationKey(operation.id)
+
+        // A value-preserving structured update obtains the row's write lock on
+        // every driver before we inspect or initialize the one-shot timestamp.
+        await db.update({
+          tableName: MAIL_DELIVERY_OPERATIONS_TABLE,
+          data: {operation_key: operationKey},
+          conditions: {operation_key: operationKey}
+        })
+        let row = await this._operationRow(db, operation.id)
+
+        if (!row) throw new Error("Required mail delivery operation is not durably registered")
+        this._validateRow({operation, row})
+
+        let firstAttemptStartedAtMs = numberOrNull(row.first_attempt_started_at_ms)
+
+        if (firstAttemptStartedAtMs === null) {
+          await db.update({
+            tableName: MAIL_DELIVERY_OPERATIONS_TABLE,
+            data: {first_attempt_started_at_ms: nowMs},
+            conditions: {operation_key: operationKey}
+          })
+          row = await this._operationRow(db, operation.id)
+          firstAttemptStartedAtMs = row ? numberOrNull(row.first_attempt_started_at_ms) : null
+
+          if (firstAttemptStartedAtMs === null) throw new Error("Failed to durably start mail delivery provider retention")
+        }
+
+        const expiresAtMs = firstAttemptStartedAtMs + operation.providerRetentionMs
+
+        if (nowMs >= expiresAtMs) {
+          throw VelociousError.safe("The required mail delivery idempotency window expired before another attempt.", {
+            code: "mail-delivery-idempotency-expired",
+            details: {
+              expiresAtMs,
+              firstAttemptStartedAtMs,
+              operationId: operation.id,
+              providerKind: operation.providerKind
+            }
+          })
+        }
+
+        return {expiresAtMs, firstAttemptStartedAtMs}
+      })
+    })
+  }
+
+  /**
+   * Loads one operation by its fixed-size digest key.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {string} operationId - Operation id.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>> | null>} - Row or null.
+   */
+  async _operationRow(db, operationId) {
+    const rows = await db
+      .newQuery()
+      .from(MAIL_DELIVERY_OPERATIONS_TABLE)
+      .where({operation_key: mailDeliveryOperationKey(operationId)})
+      .limit(1)
+      .results()
+
+    return rows[0] ? /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (rows[0]) : null
+  }
+
+  /**
+   * Validates immutable durable fields without including mail content in failures.
+   * @param {object} args - Validation input.
+   * @param {import("./index.js").MailerDeliveryOperation} args.operation - Persisted payload operation.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.row - Durable operation row.
+   * @returns {void}
+   */
+  _validateRow({operation, row}) {
+    const matches = String(row.operation_id) === operation.id
+      && String(row.payload_digest) === operation.payloadDigest
+      && String(row.provider_kind) === operation.providerKind
+      && numberOrNull(row.provider_retention_ms) === operation.providerRetentionMs
+
+    if (!matches) {
+      throw VelociousError.safe("The durable mail delivery operation does not match the persisted payload or provider.", {
+        code: "mail-delivery-idempotency-conflict"
+      })
+    }
+  }
+}
+
+/**
+ * Normalizes a database integer.
+ * @param {ReturnType<typeof JSON.parse>} value - Database value.
+ * @returns {number | null} - Number or null.
+ */
+function numberOrNull(value) {
+  if (value === null || value === undefined || value === "") return null
+  const number = Number(value)
+
+  return Number.isNaN(number) ? null : number
+}

package/build/mailer/delivery-operation.js

@@ -0,0 +1,205 @@
+// @ts-check
+
+import {createHash} from "crypto"
+import VelociousError from "../velocious-error.js"
+import stableJsonStringify from "../utils/stable-json.js"
+
+export const MAIL_DELIVERY_JOB_NAME = "MailDeliveryJob"
+export const MAIL_DELIVERY_OPERATIONS_TABLE = "mailer_delivery_operations"
+const PAYLOAD_DIGEST_FORMAT = "velocious-mail-delivery-payload-v1"
+
+/**
+ * Reads and validates a backend's provider idempotency capability.
+ * @param {object} args - Capability input.
+ * @param {import("../configuration-types.js").MailerBackend | undefined} args.backend - Configured backend.
+ * @param {import("./index.js").MailerDeliveryOperationRequest | import("./index.js").MailerDeliveryOperation} args.deliveryOperation - Required operation.
+ * @param {import("./index.js").MailerDeliveryPayload} args.payload - Rendered or persisted payload.
+ * @returns {import("./index.js").MailerDeliveryIdempotencyCapability} - Capability.
+ */
+export function requireDeliveryIdempotencyCapability({backend, deliveryOperation, payload}) {
+  if (!backend || typeof backend.deliveryIdempotencyCapability !== "function") {
+    throw VelociousError.safe("The configured mailer backend does not support required provider idempotency.", {
+      code: "mail-delivery-idempotency-unsupported"
+    })
+  }
+
+  const capability = backend.deliveryIdempotencyCapability()
+
+  if (!capability || typeof capability.providerKind !== "string" || capability.providerKind.length === 0) {
+    throw new Error("Mailer backend delivery idempotency capability requires a non-empty providerKind")
+  }
+  if (!Number.isSafeInteger(capability.retentionMs) || capability.retentionMs <= 0) {
+    throw new Error("Mailer backend delivery idempotency capability requires a positive safe-integer retentionMs")
+  }
+
+  if (typeof backend.validateDeliveryOperation === "function") {
+    backend.validateDeliveryOperation({deliveryOperation, payload})
+  }
+
+  return capability
+}
+
+/**
+ * Normalizes one public required operation into immutable payload metadata.
+ * @param {object} args - Preparation input.
+ * @param {import("./index.js").MailerDeliveryIdempotencyCapability} args.capability - Backend capability.
+ * @param {import("./index.js").MailerDeliveryOperationRequest} args.deliveryOperation - Public operation request.
+ * @param {import("./index.js").MailerDeliveryPayload} args.payload - Rendered payload.
+ * @returns {import("./index.js").MailerDeliveryPayload} - Payload with immutable operation metadata.
+ */
+export function prepareRequiredDeliveryPayload({capability, deliveryOperation, payload}) {
+  validateDeliveryOperationRequest(deliveryOperation)
+  const payloadDigest = mailDeliveryPayloadDigest({operationId: deliveryOperation.id, payload})
+
+  return {
+    ...payload,
+    deliveryOperation: {
+      id: deliveryOperation.id,
+      idempotency: "required",
+      payloadDigest,
+      providerKind: capability.providerKind,
+      providerRetentionMs: capability.retentionMs
+    }
+  }
+}
+
+/**
+ * Builds the versioned digest for every recipient-visible/provider-relevant payload field.
+ * @param {object} args - Digest input.
+ * @param {string} args.operationId - Stable operation id.
+ * @param {import("./index.js").MailerDeliveryPayload} args.payload - Rendered payload.
+ * @returns {string} - Versioned SHA-256 digest.
+ */
+export function mailDeliveryPayloadDigest({operationId, payload}) {
+  const canonicalPayload = {
+    action: payload.action,
+    bcc: payload.bcc ?? null,
+    cc: payload.cc ?? null,
+    format: PAYLOAD_DIGEST_FORMAT,
+    from: payload.from ?? null,
+    headers: canonicalHeaders(payload.headers),
+    html: payload.html,
+    mailer: payload.mailer,
+    operationId,
+    replyTo: payload.replyTo ?? null,
+    subject: payload.subject,
+    to: payload.to
+  }
+  const digest = createHash("sha256").update(stableJsonStringify(canonicalPayload)).digest("hex")
+
+  return `sha256:v1:${digest}`
+}
+
+/**
+ * Extracts validated persisted operation metadata from a payload.
+ * @param {import("./index.js").MailerDeliveryPayload} payload - Mail payload.
+ * @returns {import("./index.js").MailerDeliveryOperation | null} - Operation or null.
+ */
+export function deliveryOperationFromPayload(payload) {
+  const operation = payload.deliveryOperation
+
+  if (!operation) return null
+  if (operation.idempotency !== "required") throw new Error("Persisted mail delivery operation idempotency must be required")
+  if (typeof operation.id !== "string" || operation.id.length === 0) throw new Error("Persisted mail delivery operation requires an id")
+  if (typeof operation.payloadDigest !== "string" || !operation.payloadDigest.startsWith("sha256:v1:")) throw new Error("Persisted mail delivery operation requires a versioned payload digest")
+  if (typeof operation.providerKind !== "string" || operation.providerKind.length === 0) throw new Error("Persisted mail delivery operation requires a provider kind")
+  if (!Number.isSafeInteger(operation.providerRetentionMs) || operation.providerRetentionMs <= 0) throw new Error("Persisted mail delivery operation requires a positive retention")
+
+  return operation
+}
+
+/**
+ * Extracts a built-in mail operation from generic job arguments.
+ * @param {string} jobName - Job class name.
+ * @param {Array<ReturnType<typeof JSON.parse>>} args - Job arguments.
+ * @returns {{operation: import("./index.js").MailerDeliveryOperation, payload: import("./index.js").MailerDeliveryPayload} | null} - Mail operation input.
+ */
+export function mailDeliveryOperationForJob(jobName, args) {
+  if (jobName !== MAIL_DELIVERY_JOB_NAME || !args[0] || typeof args[0] !== "object" || Array.isArray(args[0])) return null
+
+  const payload = /** @type {import("./index.js").MailerDeliveryPayload} */ (args[0])
+  const operation = deliveryOperationFromPayload(payload)
+
+  return operation ? {operation, payload} : null
+}
+
+/**
+ * Fixed-size primary key for a potentially long operation id.
+ * @param {string} operationId - Operation id.
+ * @returns {string} - SHA-256 operation key.
+ */
+export function mailDeliveryOperationKey(operationId) {
+  return createHash("sha256").update(`velocious-mail-delivery-operation:${operationId}`).digest("hex")
+}
+
+/**
+ * Validates provider compatibility and payload integrity before an attempt.
+ * @param {object} args - Validation input.
+ * @param {import("./index.js").MailerDeliveryIdempotencyCapability} args.capability - Current backend capability.
+ * @param {import("./index.js").MailerDeliveryPayload} args.payload - Persisted payload.
+ * @returns {import("./index.js").MailerDeliveryOperation} - Persisted operation.
+ */
+export function validateAttemptPayload({capability, payload}) {
+  const operation = deliveryOperationFromPayload(payload)
+
+  if (!operation) throw new Error("Expected a persisted mail delivery operation")
+  if (operation.providerKind !== capability.providerKind || operation.providerRetentionMs !== capability.retentionMs) {
+    throw VelociousError.safe("The configured mailer backend no longer matches the required delivery operation provider.", {
+      code: "mail-delivery-idempotency-provider-mismatch"
+    })
+  }
+
+  const currentDigest = mailDeliveryPayloadDigest({operationId: operation.id, payload})
+
+  if (currentDigest !== operation.payloadDigest) {
+    throw VelociousError.safe("The persisted mail delivery payload digest does not match its required operation.", {
+      code: "mail-delivery-idempotency-payload-mismatch"
+    })
+  }
+
+  return operation
+}
+
+/**
+ * Validates the public operation shape without accepting future semantics silently.
+ * @param {import("./index.js").MailerDeliveryOperationRequest} deliveryOperation - Public operation.
+ * @returns {void}
+ */
+function validateDeliveryOperationRequest(deliveryOperation) {
+  if (!deliveryOperation || typeof deliveryOperation !== "object" || Array.isArray(deliveryOperation)) {
+    throw VelociousError.safe("deliveryOperation must be an object.", {code: "mail-delivery-operation-invalid"})
+  }
+  if (typeof deliveryOperation.id !== "string" || deliveryOperation.id.length === 0) {
+    throw VelociousError.safe("deliveryOperation.id must be a non-empty string.", {code: "mail-delivery-operation-invalid"})
+  }
+  if (deliveryOperation.idempotency !== "required") {
+    throw VelociousError.safe('deliveryOperation.idempotency must be "required".', {code: "mail-delivery-operation-invalid"})
+  }
+
+  const keys = Object.keys(deliveryOperation)
+
+  if (keys.some((key) => key !== "id" && key !== "idempotency")) {
+    throw VelociousError.safe("deliveryOperation contains unsupported fields.", {code: "mail-delivery-operation-invalid"})
+  }
+}
+
+/**
+ * Canonicalizes case-insensitive custom headers without exposing values.
+ * @param {Record<string, string> | undefined} headers - Custom headers.
+ * @returns {Array<[string, string]>} - Sorted header pairs.
+ */
+function canonicalHeaders(headers) {
+  if (!headers) return []
+
+  const pairs = Object.entries(headers).map(([name, value]) => [name.toLowerCase(), value])
+  const names = new Set()
+
+  for (const [name] of pairs) {
+    if (names.has(name)) {
+      throw VelociousError.safe("Mail headers contain duplicate case-insensitive names.", {code: "mail-delivery-headers-invalid"})
+    }
+    names.add(name)
+  }
+
+  return /** @type {Array<[string, string]>} */ (pairs.sort(([left], [right]) => left.localeCompare(right)))
+}

package/build/mailer/delivery.js

@@ -1,5 +1,7 @@
 // @ts-check
 
+import restArgsError from "../utils/rest-args-error.js"
+
 /**
  * Represents a prepared mail delivery.
  */
@@ -52,19 +54,22 @@ export default class MailerDelivery {
 
   /**
    * Runs deliver later.
+   * @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 deliverLater() {
+  async deliverLater({deliveryOperation, ...restArgs} = {}) {
+    restArgsError(restArgs)
     const payload = await this.buildPayload()
 
-    return await this.mailer._enqueuePayload(payload)
+    return await this.mailer._enqueuePayload(payload, {deliveryOperation})
   }
 
   /**
    * Runs deliver laver.
+   * @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 deliverLaver() {
-    return await this.deliverLater()
+  async deliverLaver(options) {
+    return await this.deliverLater(options)
   }
 }

package/build/mailer/index.js

@@ -1,6 +1,10 @@
 // @ts-check
 
-/** @typedef {{to: ReturnType<typeof JSON.parse>, subject: string, from?: ReturnType<typeof JSON.parse>, cc?: ReturnType<typeof JSON.parse>, bcc?: ReturnType<typeof JSON.parse>, replyTo?: ReturnType<typeof JSON.parse>, headers?: Record<string, string>, html: string, mailer: string, action: string}} MailerDeliveryPayload */
+/** @typedef {{id: string, idempotency: "required"}} MailerDeliveryOperationRequest */
+/** @typedef {{id: string, idempotency: "required", payloadDigest: string, providerKind: string, providerRetentionMs: number}} MailerDeliveryOperation */
+/** @typedef {{providerKind: string, retentionMs: number}} MailerDeliveryIdempotencyCapability */
+/** @typedef {{deliveryOperation?: MailerDeliveryOperationRequest}} MailerDeliveryLaterOptions */
+/** @typedef {{to: ReturnType<typeof JSON.parse>, subject: string, from?: ReturnType<typeof JSON.parse>, cc?: ReturnType<typeof JSON.parse>, bcc?: ReturnType<typeof JSON.parse>, replyTo?: ReturnType<typeof JSON.parse>, headers?: Record<string, string>, html: string, mailer: string, action: string, deliveryOperation?: MailerDeliveryOperation}} MailerDeliveryPayload */
 
 import {
   clearDeliveries,