OpenFn
diff --git a/‎CHANGELOG.md‎
Lines changed: 11 additions & 2 deletions b/‎CHANGELOG.md‎
Lines changed: 11 additions & 2 deletions
diff --git a/‎lib/lightning/projects/merge_projects.ex‎
Lines changed: 61 additions & 11 deletions b/‎lib/lightning/projects/merge_projects.ex‎
Lines changed: 61 additions & 11 deletions
diff --git a/‎lib/lightning/projects/provisioner.ex‎
Lines changed: 1 addition & 4 deletions b/‎lib/lightning/projects/provisioner.ex‎
Lines changed: 1 addition & 4 deletions
diff --git a/‎lib/lightning/projects/sandboxes.ex‎
Lines changed: 112 additions & 5 deletions b/‎lib/lightning/projects/sandboxes.ex‎
Lines changed: 112 additions & 5 deletions
diff --git a/‎lib/lightning/workflows.ex‎
Lines changed: 34 additions & 11 deletions b/‎lib/lightning/workflows.ex‎
Lines changed: 34 additions & 11 deletions
diff --git a/‎lib/lightning_web/live/credential_live/credential_index_component.ex‎
Lines changed: 3 additions & 9 deletions b/‎lib/lightning_web/live/credential_live/credential_index_component.ex‎
Lines changed: 3 additions & 9 deletions
diff --git a/‎lib/lightning_web/live/credential_live/helpers.ex‎
Lines changed: 12 additions & 0 deletions b/‎lib/lightning_web/live/credential_live/helpers.ex‎
Lines changed: 12 additions & 0 deletions
@@ -28,8 +28,7 @@ and this project adheres to
 - Consolidated run and work order state definitions into single source of truth
   by adding `Run.active_states/0`, `WorkOrder.states/0`, and
   `WorkOrder.active_states/0` and replacing all hardcoded state lists across the
-  codebase
-  [#4589](https://github.com/OpenFn/lightning/issues/4589)
+  codebase [#4589](https://github.com/OpenFn/lightning/issues/4589)
 
 ### Fixed
 
@@ -38,6 +37,16 @@ and this project adheres to
   single `Lightning.Collaboration.WorkflowResolver`, so the channel join and the
   session save path can no longer disagree on whether an id should INSERT or
   UPDATE. [#4830](https://github.com/OpenFn/lightning/issues/4830)
+- Ensure that credentials are properly transferred when merging a sandbox. This
+  fixes a validation error which can occur on merge
+  [#4831](https://github.com/OpenFn/lightning/issues/4831)
+- Free up a workflow's name when it is deleted by a merge, so a later merge can
+  reuse that name [#4831](https://github.com/OpenFn/lightning/issues/4831)
+- Replace the generic "validation error" on a failed sandbox merge with a clear
+  message, naming the conflicting workflow when there is one
+  [#4831](https://github.com/OpenFn/lightning/issues/4831)
+- Add a credential created in a sandbox to its full ancestor chain, so it
+  survives a merge into any ancestor
 
 ## [2.16.7] - 2026-06-04
 
 
@@ -51,16 +51,26 @@ defmodule Lightning.Projects.MergeProjects do
         opts
       ) do
     source_project =
-      Repo.preload(source_project, workflows: [:jobs, :triggers, :edges])
+      Repo.preload(source_project,
+        workflows: [:jobs, :triggers, :edges],
+        project_credentials: []
+      )
 
     target_project =
-      Repo.preload(target_project, workflows: [:jobs, :triggers, :edges])
+      Repo.preload(target_project,
+        workflows: [:jobs, :triggers, :edges],
+        project_credentials: []
+      )
 
-    merge_project(
-      Map.from_struct(source_project),
-      Map.from_struct(target_project),
-      opts
-    )
+    credential_map =
+      build_credential_remap(
+        source_project.project_credentials,
+        target_project.project_credentials
+      )
+
+    Map.from_struct(source_project)
+    |> merge_project(Map.from_struct(target_project), opts)
+    |> remap_document_credentials(credential_map)
   end
 
   def merge_project(source_project, target_project, opts) do
@@ -552,10 +562,6 @@ defmodule Lightning.Projects.MergeProjects do
             |> then(fn job_attrs ->
               if target_job do
                 job_attrs
-                |> Map.put(
-                  :project_credential_id,
-                  target_job.project_credential_id
-                )
                 |> Map.put(
                   :keychain_credential_id,
                   target_job.keychain_credential_id
@@ -585,6 +591,50 @@ defmodule Lightning.Projects.MergeProjects do
     {new_mapping, merged_from_source ++ deleted_targets}
   end
 
+  # Builds a map of `source_project_credential_id => target_project_credential_id`
+  # by matching on the shared underlying `credential_id`
+  defp build_credential_remap(
+         source_project_credentials,
+         target_project_credentials
+       ) do
+    target_by_credential =
+      Map.new(target_project_credentials, &{&1.credential_id, &1.id})
+
+    Map.new(source_project_credentials, fn pc ->
+      {pc.id, Map.get(target_by_credential, pc.credential_id)}
+    end)
+  end
+
+  defp remap_document_credentials(document, credential_map)
+       when map_size(credential_map) == 0,
+       do: document
+
+  defp remap_document_credentials(document, credential_map) do
+    Map.update(document, "workflows", [], fn workflows ->
+      Enum.map(workflows, &remap_workflow_credentials(&1, credential_map))
+    end)
+  end
+
+  defp remap_workflow_credentials(%{"jobs" => jobs} = workflow, credential_map) do
+    Map.put(
+      workflow,
+      "jobs",
+      Enum.map(jobs, &remap_job_credential(&1, credential_map))
+    )
+  end
+
+  defp remap_workflow_credentials(workflow, _credential_map), do: workflow
+
+  defp remap_job_credential(
+         %{"project_credential_id" => pc_id} = job,
+         credential_map
+       )
+       when not is_nil(pc_id) do
+    Map.put(job, "project_credential_id", Map.get(credential_map, pc_id, pc_id))
+  end
+
+  defp remap_job_credential(job, _credential_map), do: job
+
   defp build_merged_triggers(source_triggers, target_triggers, trigger_mappings) do
     # Process source triggers (matched and new)
     {new_mapping, merged_from_source} =
 
@@ -687,10 +687,7 @@ defmodule Lightning.Projects.Provisioner do
       {true, others} when map_size(others) == 0 ->
         changeset
         |> Map.put(:changes, others)
-        |> put_change(
-          :deleted_at,
-          DateTime.utc_now() |> DateTime.truncate(:second)
-        )
+        |> Workflows.soft_delete_changeset()
 
       {true, others} when map_size(others) > 0 ->
         changeset
 
@@ -62,6 +62,8 @@ defmodule Lightning.Projects.Sandboxes do
   alias Lightning.Workflows.WorkflowVersion
   alias Lightning.WorkflowVersions
 
+  require Logger
+
   @typedoc """
   Attributes for creating a new sandbox via `provision/3`.
 
@@ -163,31 +165,136 @@ defmodule Lightning.Projects.Sandboxes do
   * `source` - The sandbox project being merged
   * `target` - The project receiving the merge
   * `actor` - The user performing the merge
-  * `opts` - Merge options (`:selected_workflow_ids`, `:deleted_target_workflow_ids`)
+  * `opts` - Merge options (`:selected_workflow_ids`,
+    `:deleted_target_workflow_ids`, `:selected_credential_ids`)
+
+  ## Credential attachment
+
+  A credential that lives only in the sandbox (the target has no
+  `project_credential` for its underlying `credential_id`) would otherwise be
+  dropped on merge, since the remap only matches on shared credentials. Pass
+  `:selected_credential_ids` (a list of the sandbox `project_credential` ids the
+  caller chose to carry over) and each one is attached to the target before the
+  document is imported, so the remap finds a match instead of dropping it.
+  Sandbox `project_credentials` left out of the list stay dropped. Only regular
+  `project_credentials` are handled here; keychain credentials are out of scope.
 
   ## Returns
   * `{:ok, updated_target}` - Merge succeeded
-  * `{:error, reason}` - Workflow merge or collection sync failed
+  * `{:error, merge_error}` - Merge failed, classified into a domain reason
+
+  Failures are returned as typed reasons (see `t:merge_error/0`) so callers can
+  render user-facing copy without inspecting changeset internals. The full
+  validation detail is logged for diagnosis.
   """
+  @type merge_error ::
+          :merge_failed | Lightning.Extensions.UsageLimiting.message()
+
   @spec merge(Project.t(), Project.t(), User.t(), map()) ::
-          {:ok, Project.t()} | {:error, term()}
+          {:ok, Project.t()} | {:error, merge_error()}
   def merge(
         %Project{} = source,
         %Project{} = target,
         %User{} = actor,
         opts \\ %{}
       ) do
-    merge_doc = MergeProjects.merge_project(source, target, opts)
+    selected_credential_ids = Map.get(opts, :selected_credential_ids, [])
 
     Repo.transact(fn ->
-      with {:ok, updated_target} <-
+      with :ok <-
+             attach_selected_credentials(source, target, selected_credential_ids),
+           # Re-preload so the credential remap sees the just-attached
+           # associations; merge_project skips the preload if they're already loaded.
+           target =
+             Repo.preload(target, [project_credentials: []], force: true),
+           merge_doc = MergeProjects.merge_project(source, target, opts),
+           {:ok, updated_target} <-
              Provisioner.import_document(target, actor, merge_doc,
                allow_stale: true
              ),
            {:ok, _} <- sync_collections(source, target) do
         {:ok, updated_target}
       end
     end)
+    |> case do
+      {:ok, _} = ok -> ok
+      {:error, reason} -> {:error, classify_merge_error(reason)}
+    end
+  end
+
+  # Attaches the chosen sandbox-only credentials to the target so the merge
+  # remap can match them. The credential diff is recomputed from the database
+  # rather than trusting the caller's list verbatim: only sandbox
+  # project_credentials whose underlying credential the target still lacks are
+  # attached, and ON CONFLICT DO NOTHING guards against a concurrent attach.
+  defp attach_selected_credentials(_source, _target, []), do: :ok
+
+  defp attach_selected_credentials(source, target, selected_credential_ids) do
+    selected_set = MapSet.new(selected_credential_ids)
+
+    target_credential_ids =
+      from(pc in ProjectCredential,
+        where: pc.project_id == ^target.id,
+        select: pc.credential_id
+      )
+      |> Repo.all()
+      |> MapSet.new()
+
+    rows =
+      from(pc in ProjectCredential,
+        where: pc.project_id == ^source.id,
+        select: %{id: pc.id, credential_id: pc.credential_id}
+      )
+      |> Repo.all()
+      |> Enum.filter(fn pc ->
+        MapSet.member?(selected_set, pc.id) and
+          not MapSet.member?(target_credential_ids, pc.credential_id)
+      end)
+      |> build_target_credential_rows(target.id)
+
+    Repo.insert_all(ProjectCredential, rows,
+      on_conflict: :nothing,
+      conflict_target: [:project_id, :credential_id]
+    )
+
+    :ok
+  end
+
+  defp build_target_credential_rows(source_credentials, target_id) do
+    now = DateTime.utc_now() |> DateTime.truncate(:second)
+
+    Enum.map(source_credentials, fn pc ->
+      %{
+        id: Ecto.UUID.generate(),
+        project_id: target_id,
+        credential_id: pc.credential_id,
+        inserted_at: now,
+        updated_at: now
+      }
+    end)
+  end
+
+  # A failed merge is sensitive (it can block or lose a user's work), so every
+  # failure is logged at :error to surface in Sentry. A usage-limit message is
+  # an expected, user-actionable block, so it passes through unlogged.
+  defp classify_merge_error(%Ecto.Changeset{} = changeset) do
+    Logger.error(
+      "Sandbox merge failed. #{inspect(merge_error_details(changeset))}"
+    )
+
+    :merge_failed
+  end
+
+  defp classify_merge_error(%{text: _} = usage_limit_message),
+    do: usage_limit_message
+
+  defp classify_merge_error(reason) do
+    Logger.error("Sandbox merge failed. #{inspect(reason)}")
+    :merge_failed
+  end
+
+  defp merge_error_details(changeset) do
+    Ecto.Changeset.traverse_errors(changeset, fn {message, _opts} -> message end)
   end
 
   @doc """
 
@@ -717,16 +717,10 @@ defmodule Lightning.Workflows do
         where: t.workflow_id == ^workflow.id
       )
 
-    new_name = resolve_name_for_pending_deletion(workflow)
-
     Multi.new()
     |> Multi.update(
       :workflow,
-      workflow
-      |> Workflow.request_deletion_changeset(%{
-        "deleted_at" => DateTime.utc_now()
-      })
-      |> Ecto.Changeset.put_change(:name, new_name)
+      soft_delete_changeset(Ecto.Changeset.change(workflow))
     )
     |> Multi.insert(:audit, Audit.marked_for_deletion(workflow.id, actor))
     |> Multi.update_all(
@@ -744,10 +738,39 @@ defmodule Lightning.Workflows do
     end)
   end
 
-  defp resolve_name_for_pending_deletion(%Workflow{
-         name: name,
-         project_id: project_id
-       }) do
+  @doc """
+  Marks a workflow deleted and frees its name for reuse, in one step.
+
+  The single soft-delete transition both `mark_for_deletion/3` and the
+  provisioner route through, so a deleted workflow can never keep its name
+  reserved on a hidden row.
+  """
+  @spec soft_delete_changeset(Ecto.Changeset.t(Workflow.t())) ::
+          Ecto.Changeset.t(Workflow.t())
+  def soft_delete_changeset(
+        %Ecto.Changeset{data: %Workflow{} = workflow} = changeset
+      ) do
+    changeset
+    |> Workflow.request_deletion_changeset(%{
+      deleted_at: DateTime.utc_now() |> DateTime.truncate(:second)
+    })
+    |> Ecto.Changeset.put_change(
+      :name,
+      resolve_name_for_pending_deletion(workflow)
+    )
+  end
+
+  @doc """
+  Computes the `name_del`-style name a workflow should take when it is soft
+  deleted, so it frees up its original name for reuse within the project.
+
+  Used by `soft_delete_changeset/1`, which every delete path routes through.
+  """
+  @spec resolve_name_for_pending_deletion(Workflow.t()) :: String.t()
+  def resolve_name_for_pending_deletion(%Workflow{
+        name: name,
+        project_id: project_id
+      }) do
     base_name = "#{name}_del"
 
     existing_names =
 
@@ -91,15 +91,9 @@ defmodule LightningWeb.CredentialLive.CredentialIndexComponent do
   def handle_event("show_modal", %{"target" => "new_credential"}, socket) do
     if socket.assigns.can_create_project_credential do
       project_credentials =
-        if socket.assigns.project do
-          [
-            %Lightning.Projects.ProjectCredential{
-              project_id: socket.assigns.project.id
-            }
-          ]
-        else
-          []
-        end
+        LightningWeb.CredentialLive.Helpers.default_project_credentials(
+          socket.assigns.project
+        )
 
       {:noreply,
        assign(socket,
 
@@ -145,6 +145,18 @@ defmodule LightningWeb.CredentialLive.Helpers do
     }
   end
 
+  @doc """
+  The `project_credentials` to pre-select when creating a credential: only the
+  active project. Empty when there is no project context.
+  """
+  @spec default_project_credentials(Lightning.Projects.Project.t() | nil) ::
+          [Lightning.Projects.ProjectCredential.t()]
+  def default_project_credentials(nil), do: []
+
+  def default_project_credentials(%Lightning.Projects.Project{id: id}) do
+    [%Lightning.Projects.ProjectCredential{project_id: id}]
+  end
+
   def handle_save_response(socket, credential) do
     if socket.assigns[:on_save] do
       socket.assigns[:on_save].(credential)