bikoret/vav_pipeline/lib/vav_pipeline.ex

defmodule VavPipeline do
  @moduledoc """
  The Bereishit processing cycle.

  Each step chains to the next via |> (vav-consecutive).

  CRITICAL: The pipeline does not begin with a processing step.
  It begins with RECEPTION. The ShemaContext is built first —
  the system hears before it speaks. Then every processing step
  operates WITHIN the received context, never modifying it.

  Na'aseh v'nishma — but the order of execution is:
  nishma (hear/receive context), THEN na'aseh (process within it).
  """

  alias VavPipeline.{Shema, Cloud, Manna, BereishitCycle, Chatzotzrot}

  @type scope :: %{
          book: String.t(),
          chapter: pos_integer(),
          verse: pos_integer()
        }

  @type input :: %{
          source: String.t(),
          verse_scope: scope(),
          content: String.t()
        }

  @type cycle_result ::
          {:ok, map()}
          | {:rejected, String.t()}
          | {:unresolved, map()}
          | {:transition, atom()}
          | {:waiting, atom()}
          | {:halted, atom(), String.t()}

  @doc """
  Process input through the Bereishit cycle.

  1. Build ShemaContext (nishma — hear first)
  2. Check cloud — if moving, signal breaking camp
  3. Check manna — if absent, wait
  4. Process through cycle stages (na'aseh — within what was received)
  """
  @spec process(input()) :: cycle_result()
  def process(input) do
    # === NISHMA: Hear first ===
    case Shema.receive_context(input.verse_scope) do
      {:error, reason} ->
        {:halted, :context_failed, reason}

      {:ok, context} ->
        # === Check cloud before anything else ===
        case context.cloud_state do
          :moving ->
            Chatzotzrot.signal(:breaking_camp)
            {:transition, :cloud_lifted}

          {:major_transition, signal, _params} ->
            {:transition, signal}

          :cloud_not_visible ->
            {:waiting, :cloud_not_visible}

          :camped ->
            # === Check manna ===
            case context.daily_provision do
              :no_provision ->
                {:waiting, :no_provision}

              _provision ->
                # === NA'ASEH: Now process, within what was received ===
                BereishitCycle.execute(input, context)
            end
        end
    end
  end

  @doc """
  Verify the pipeline is operational.
  Checks L1 integrity, cloud state, and manna provision.
  """
  @spec verify() :: :ok | {:error, String.t()}
  def verify do
    with :ok <- VavPipeline.L1Reader.verify_integrity(),
         {:ok, _} <- Cloud.check(),
         {:ok, _} <- Manna.check() do
      :ok
    end
  end
end