oi

defmodule Oi do
  @doc_header """

  Oi means Orchid integration.

  """

  @external_resource readme = Path.join([__DIR__, "../README.md"])
  @doc_main readme

            |> File.read!()

            |> String.split("<!-- MDOC -->")

            |> Enum.fetch!(1)

  @moduledoc @doc_header <> @doc_main

  @type name :: String.t()

  alias Oi.Workspace
  alias Oi.{Compiler, Dispatcher, Configurator}
  alias Oi.Workspace.{Planning, Drafting}

  @doc """

  Phase 1: Compile graph into static bundles + plan.



  Pure topology — no interventions. Result stored in `workspace.static_bundles`

  and `workspace.plan`. Reusable across different intervention sets.

  """
  @spec compile(Workspace.t()) :: {:ok, Workspace.t()} | {:error, :cycle_detected}
  def compile(%Workspace{} = ws) do
    case Compiler.compile_graph(ws.graph, ws.cluster) do
      {:ok, bundles} ->
        {:ok, plan} = Planning.build(bundles)
        {:ok, %{ws | static_bundles: bundles, plan: plan}}

      {:error, _} = err ->
        err
    end
  end

  @doc """

  Phase 2: Dispatch plan with interventions, filling `drafting`.



  Interventions can be overridden via the `:interventions` option —

  useful for A/B testing with the same compiled plan.



  ## Options



    * `:interventions` — overrides `workspace.interventions` (default)

    * `:executor` — `Oi.Executor.Sync` (default), `Oi.Executor.TaskSup`, or `Oi.Executor.Pool`

    * `:executor_opts` — passed to the executor (e.g. `[sup: MyTaskSup]`)

    * `:plugins` — OrchidPlugin pipeline

    * `:orchid_baggage` — merged into Orchid run baggage



  ## Examples



      # Compile once

      {:ok, ws} = Oi.compile(ws)



      # Dispatch with default interventions

      {:ok, ws} = Oi.dispatch(ws)



      # Dispatch with swapped interventions (reuses compiled plan)

      {:ok, ws_b} = Oi.dispatch(ws, interventions: other_interventions)



      # With Task.Supervisor

      {:ok, ws} = Oi.dispatch(ws,

        executor: Oi.Executor.TaskSup,

        executor_opts: [sup: Oi.Session.tasks_tuple("svs-1")]

      )

  """
  @spec dispatch(Workspace.t(), keyword()) :: {:ok, Workspace.t()} | {:error, term()}
  def dispatch(%Workspace{} = ws, opts \\ []) do
    case ws.plan do
      nil ->
        {:error, :not_compiled}

      %Planning.Plan{} ->
        interventions = Keyword.get(opts, :interventions, ws.interventions)
        bound_bundles = Compiler.bind(ws.static_bundles, interventions)

        # Rebuild plan with bound bundles

        {:ok, bound_plan} = Planning.build(bound_bundles)

        conf = Configurator.new(opts)
        drafting = Drafting.new()

        case Dispatcher.dispatch(bound_plan, drafting, conf) do
          {:ok, final_drafting} ->
            {:ok, %{ws | drafting: final_drafting}}

          {:error, _} = err ->
            err
        end
    end
  end
end