therefore reports success without contradicting the record.

  """

  @spec complete(Effect.t() | String.t()) :: {:ok, Effect.t()} | {:error, :not_found}

  def complete(%Effect{id: id}), do: complete(id)

  def complete(%Effect{id: id}), do: complete(id, nil)

  def complete(id) when is_binary(id) do

  def complete(id) when is_binary(id), do: complete(id, nil)

  @doc """

  Record that an effect's handler succeeded, with an optional result payload.

  A handler that reached a terminal outcome without an external result can pass

  `nil`; a handler that produced an explicit result map can record it. The same

  idempotency rule applies: a completed effect returns its existing row.

  """

  @spec complete(Effect.t() | String.t(), map() | nil) :: {:ok, Effect.t()} | {:error, :not_found}

  def complete(%Effect{id: id}, result), do: complete(id, result)

  def complete(id, result) when is_binary(id) do

    now = DateTime.utc_now()

    {_count, updated} =

          lease_owner: nil,

          lease_expires_at: nil,

          last_error: nil,

          result: result,

          completed_at: now,

          updated_at: now

        ]

    field :lease_owner, :string

    field :lease_expires_at, :utc_datetime_usec

    field :last_error, :string

    field :result, :map

    field :claimed_at, :utc_datetime_usec

    field :completed_at, :utc_datetime_usec

      :source_sequence,

      :idempotency_key,

      :maximum_attempts,

      :available_at

      :available_at,

      :result

    ])

    |> validate_required([

      :kind,

defmodule OpenAgents.Effects.Handlers.EmailDelivery do

  @moduledoc """

  Drives an `email.delivery` effect to a terminal state.

  The payload carries the notification `dedupe_key` and optional `data`. When

  `data` does not contain a `to` recipient, the handler records a successful

  `nothing_to_send_to` terminal outcome. Otherwise it calls the configured

  `OpenAgents.Notifications.Delivery` adapter, which is a future seam: no real

  send happens unless a provider is configured.

  """

  @behaviour OpenAgents.Effects.Handler

  alias OpenAgents.Effects.Effect

  alias OpenAgents.Notifications.Delivery

  @impl OpenAgents.Effects.Handler

  def run(%Effect{payload: payload}, _idempotency_key) do

    data = Map.get(payload, "data", %{})

    case recipient(data) do

      nil ->

        {:ok, %{"outcome" => "nothing_to_send_to"}}

      to ->

        Delivery.adapter().deliver(to, data)

    end

  end

  defp recipient(data) when is_map(data) do

    case Map.get(data, "to") do

      value when is_binary(value) and value != "" -> value

      _ -> nil

    end

  end

end

  """

  @default_handlers %{

    "work.launch_worker" => OpenAgents.Effects.Handlers.WorkLaunch

    "work.launch_worker" => OpenAgents.Effects.Handlers.WorkLaunch,

    "email.delivery" => OpenAgents.Effects.Handlers.EmailDelivery

  }

  @doc "Every admitted effect kind and its handler."

        {:ok, _effect} = Effects.complete(effect)

        :ok

      {:ok, %{} = result} ->

        {:ok, _effect} = Effects.complete(effect, result)

        :ok

      {:ok, _result} ->

        {:ok, _effect} = Effects.complete(effect)

        :ok

defmodule OpenAgents.Notifications.Delivery do

  @moduledoc """

  Durable outbound email delivery seam for notifications.

  Enqueues one `email.delivery` effect keyed to a notification `dedupe_key`.

  A recipient is optional in the caller's data; if none is provided the handler

  records a terminal `nothing_to_send_to` outcome instead of a failure.

  No real send happens here. The adapter is a future seam: the default

  `OpenAgents.Notifications.Delivery.NullAdapter` refuses unless a real

  provider is configured, and the caller supplies a `to` address.

  """

  alias OpenAgents.Effects

  alias OpenAgents.Notifications.Notification

  @kind "email.delivery"

  @source_kind "notification"

  @doc """

  Enqueue an email delivery for a `Notification` or a bare `dedupe_key`.

  Accepted shapes:

    * `%Notification{}`

    * a map or keyword with `:dedupe_key` and optional `:data`, `:user_id`,

      `:notification_id`, and `:maximum_attempts`

  When a `user_id` is known, the idempotency key is scoped to that user so the

  same `dedupe_key` for two different accounts stays two distinct deliveries.

  """

  @spec enqueue(Notification.t() | map() | keyword()) ::

          {:ok, Effects.Effect.t()} | {:error, term()}

  def enqueue(%Notification{} = notification) do

    enqueue(%{

      dedupe_key: notification.dedupe_key,

      user_id: notification.user_id,

      notification_id: notification.id,

      data: %{}

    })

  end

  def enqueue(attrs) when is_list(attrs), do: enqueue(Map.new(attrs))

  def enqueue(attrs) when is_map(attrs) do

    dedupe_key = fetch!(attrs, :dedupe_key)

    user_id = Map.get(attrs, :user_id)

    notification_id = Map.get(attrs, :notification_id)

    data = Map.get(attrs, :data) || %{}

    idempotency_source = if user_id, do: "#{user_id}/#{dedupe_key}", else: dedupe_key

    Effects.enqueue(@kind, %{

      payload: %{

        "dedupe_key" => dedupe_key,

        "user_id" => user_id,

        "notification_id" => notification_id,

        "data" => data

      },

      source_kind: @source_kind,

      source_id: dedupe_key,

      idempotency_key: Effects.idempotency_key(@kind, @source_kind, idempotency_source),

      maximum_attempts: Map.get(attrs, :maximum_attempts, 5)

    })

  end

  @doc "The configured delivery adapter. Defaults to the no-op NullAdapter."

  @spec adapter() :: module()

  def adapter do

    :openagents

    |> Application.get_env(__MODULE__, [])

    |> Keyword.get(:adapter, OpenAgents.Notifications.Delivery.NullAdapter)

  end

  defp fetch!(attrs, key) do

    case Map.fetch(attrs, key) do

      {:ok, value} when value != nil -> value

      _ -> raise ArgumentError, "delivery enqueue requires #{inspect(key)}"

    end

  end

end

defmodule OpenAgents.Notifications.Delivery.Adapter do

  @moduledoc """

  Behaviour for a future email delivery adapter.

  The adapter is a seam: nothing here performs a real send. A concrete

  implementation receives the recipient address and the caller's data map and

  returns either an ok result map or an error reason that the durable outbox

  will retry.

  """

  @doc "Deliver `data` to `recipient`. Returns `:ok`, `{:ok, result}`, or `{:error, reason}`."

  @callback deliver(recipient :: String.t() | nil, data :: map()) ::

              :ok | {:ok, map()} | {:error, term()}

end

defmodule OpenAgents.Notifications.Delivery.NullAdapter do

  @moduledoc """

  Default no-op email delivery adapter.

  No provider is configured, so a delivery that has a recipient cannot be sent.

  The handler returns an error and the durable outbox retries up to its

  `maximum_attempts`. A delivery without a recipient is handled before the

  adapter is ever called.

  """

  @behaviour OpenAgents.Notifications.Delivery.Adapter

  @impl true

  def deliver(_recipient, _data), do: {:error, :no_provider_configured}

end

    20260824230730,

    20260824231951,

    20260825024500,

    20260825054906

    20260825054906,

    20260825102408

  ],

  "required_tables": [

    "users",

defmodule OpenAgents.Repo.Migrations.AddEmailDeliveryResultToEffects do

  use Ecto.Migration

  def change do

    alter table(:effects) do

      add :result, :map

    end

  end

end

defmodule OpenAgents.Notifications.DeliveryTest do

  @moduledoc """

  Proofs for the durable, decision-independent outbound email seam.

  These tests intentionally do not configure a real provider. They exercise the

  outbox invariants (idempotency, retry, terminal failure, and no-recipient

  handling) through the `email.delivery` effect.

  """

  use OpenAgents.DataCase, async: false

  alias OpenAgents.Effects

  alias OpenAgents.Effects.Effect

  alias OpenAgents.Effects.Worker

  alias OpenAgents.Notifications.Delivery

  defmodule FailingAdapter do

    @behaviour OpenAgents.Notifications.Delivery.Adapter

    @impl true

    def deliver(_recipient, _data), do: {:error, :test_failure}

  end

  setup do

    Application.put_env(:openagents, OpenAgents.Notifications.Delivery, adapter: FailingAdapter)

    on_exit(fn ->

      Application.delete_env(:openagents, OpenAgents.Notifications.Delivery)

    end)

    :ok

  end

  describe "enqueue/1" do

    test "records one delivery per dedupe key, no matter how many times it is enqueued" do

      {:ok, first} = Delivery.enqueue(dedupe_key: "issue:1:opened", user_id: "user-a")

      {:ok, second} = Delivery.enqueue(dedupe_key: "issue:1:opened", user_id: "user-a")

      assert first.id == second.id

      assert Repo.aggregate(Effect, :count) == 1

      assert first.payload["dedupe_key"] == "issue:1:opened"

    end

    test "a different user with the same dedupe key gets a distinct delivery" do

      {:ok, first} = Delivery.enqueue(dedupe_key: "issue:1:opened", user_id: "user-a")

      {:ok, second} = Delivery.enqueue(dedupe_key: "issue:1:opened", user_id: "user-b")

      refute first.id == second.id

    end

  end

  describe "handler dispatch" do

    test "a failed attempt increments attempts and reschedules the next try" do

      {:ok, effect} =

        Delivery.enqueue(

          dedupe_key: "fail-once",

          user_id: "user-a",

          data: %{"to" => "test@example.com"}

        )

      before = DateTime.utc_now()

      assert %{completed: 0, failed: 1} = Worker.run_once(identity: "worker-a")

      failed = Effects.get(effect.id)

      assert failed.status == "pending"

      assert failed.attempts == 1

      assert failed.last_error =~ "test_failure"

      assert DateTime.compare(failed.available_at, before) == :gt

      later = DateTime.add(failed.available_at, 1, :second)

      assert [retried] = Effects.claim_batch("worker-b", now: later)

      assert retried.attempts == 2

    end

    test "attempts stop at a terminal failed state" do

      {:ok, effect} =

        Delivery.enqueue(

          dedupe_key: "doomed",

          user_id: "user-a",

          data: %{"to" => "test@example.com"},

          maximum_attempts: 2

        )

      assert %{completed: 0, failed: 1} = Worker.run_once(identity: "worker-a")

      first = Effects.get(effect.id)

      assert first.status == "pending"

      assert first.attempts == 1

      later = DateTime.add(first.available_at, 1, :second)

      assert [claimed] = Effects.claim_batch("worker-b", now: later)

      assert claimed.attempts == 2

      assert :error = Worker.dispatch(claimed)

      dead = Effects.get(effect.id)

      assert dead.status == "failed"

      assert dead.attempts == 2

      assert dead.completed_at != nil

      assert dead.lease_owner == nil

      far_future = DateTime.add(dead.available_at, 3_600, :second)

      assert Effects.claim_batch("worker-c", now: far_future) == []

    end

    test "a delivery with no recipient records nothing to send to, not a failure" do

      {:ok, effect} =

        Delivery.enqueue(

          dedupe_key: "no-recipient",

          user_id: "user-a",

          data: %{"subject" => "hello"}

        )

      assert %{completed: 1, failed: 0} = Worker.run_once(identity: "worker-a")

      done = Effects.get(effect.id)

      assert done.status == "done"

      assert done.attempts == 1

      assert done.result == %{"outcome" => "nothing_to_send_to"}

      assert done.last_error == nil

      assert done.completed_at != nil

    end

  end

end