cannot prove, and whether it has been performed. **Performed** means someone

ran it and recorded the result here. Anything else says so.

`test/openagents/forge/exit_rehearsal_runbook_test.exs` checks every

`OpenAgents` module and function this document names against the compiled

code. Rehearsal 3's step 3 once named `OpenAgents.Forge.Sync.rebuild/1`

before that function existed (#189), and no invariant could notice, because

invariants read compiled modules and the step was a string in this file. A

renamed or removed function now turns a test red instead of leaving a step

that reads as executable.

## Rehearsal status

| Rehearsal | Executable proof | Performed against the live forge |

4. Move the affected bare repository cache aside. Do not delete or modify WAL

   indexes or WAL objects. Keep the moved cache until verification finishes.

5. Trigger repository synchronization or restart the application so boot

   convergence replays the WAL into a new local cache.

   convergence replays the WAL into a new local cache. To force a discard and

   replay in one call, run

   `bin/openagents rpc 'OpenAgents.Forge.Sync.rebuild("{storage_key}")'`. It

   rebuilds the projection from sequence zero in a sibling directory, verifies

   every authoritative ref, and swaps the result in atomically. On success it

   deletes the previous cache, so complete step 4 first when you want to keep

   the old cache until verification finishes.

6. Verify the applied WAL sequence, every authoritative ref, the reported blob,

   Git ref advertisement, and `/health` on that node.

7. Restore load-balancer admission only after `forge_cache_ready` and the

defmodule OpenAgents.Forge.ExitRehearsalRunbookTest do

  @moduledoc """

  #189's third acceptance criterion. Rehearsal 3's step 3 told an operator to

  run `OpenAgents.Forge.Sync.rebuild/1` before that function existed, and no

  invariant could notice: invariants read compiled modules, and the procedure

  was a string in a Markdown file. This test reads the strings.

  Three shapes of reference in `docs/forge-exit-rehearsals.md` are checked

  against the compiled code:

  - every `bin/openagents rpc '…'` command in any document under `docs/`

    parses as Elixir, and every `OpenAgents` function it calls is exported at

    the called arity;

  - every qualified `OpenAgents.Module.function/arity` reference resolves;

  - every bare `function/arity` reference in code font is exported by at

    least one module the document names.

  A renamed or removed function now turns this test red instead of leaving a

  runbook step that reads as executable but is not.

  """

  use ExUnit.Case, async: true

  @runbook "docs/forge-exit-rehearsals.md"

  test "every rpc command in the documentation calls functions that exist" do

    commands =

      for path <- Path.wildcard("docs/**/*.md"),

          [command] <-

            Regex.scan(~r{bin/openagents rpc '([^']+)'}, File.read!(path),

              capture: :all_but_first

            ),

          do: {path, command}

    assert Enum.any?(commands, fn {path, _command} -> path == @runbook end),

           "#{@runbook} no longer contains rpc commands; retire this test"

    for {path, command} <- commands do

      calls =

        command

        |> Code.string_to_quoted!()

        |> expand_pipes()

        |> collect_openagents_calls()

      assert calls != [], "rpc command in #{path} calls no OpenAgents function: #{command}"

      for {module, function, arity} <- calls do

        assert Code.ensure_loaded?(module),

               "#{inspect(module)} is named in #{path} but does not exist"

        assert function_exported?(module, function, arity),

               "#{inspect(module)}.#{function}/#{arity} is named in #{path} " <>

                 "but is not exported at that arity"

      end

    end

  end

  test "every qualified function/arity reference in the runbook resolves" do

    references =

      Regex.scan(

        ~r/(OpenAgents(?:\.[A-Z][A-Za-z0-9_]*)+)\.([a-z_][a-z0-9_]*[?!]?)\/(\d+)/,

        runbook(),

        capture: :all_but_first

      )

    for [module_name, function, arity] <- references do

      module = Module.concat([module_name])

      function = String.to_atom(function)

      arity = String.to_integer(arity)

      assert Code.ensure_loaded?(module),

             "#{module_name} is named in #{@runbook} but does not exist"

      assert function_exported?(module, function, arity),

             "#{module_name}.#{function}/#{arity} is named in #{@runbook} but is not exported"

    end

  end

  test "every module the runbook names exists" do

    modules = named_modules()

    assert OpenAgents.Forge.Sync in modules

    for module <- modules do

      assert Code.ensure_loaded?(module),

             "#{inspect(module)} is named in #{@runbook} but does not exist"

    end

  end

  test "every bare function/arity reference is exported by a module the runbook names" do

    # `function_exported?/3` does not load a module, so load them first. The

    # modules-exist test owns the assertion that loading never fails.

    modules = Enum.filter(named_modules(), &Code.ensure_loaded?/1)

    references =

      Regex.scan(~r/`([a-z_][a-z0-9_]*[?!]?)\/(\d+)`/, runbook(), capture: :all_but_first)

    # The reference this test exists for. Its absence means the document

    # changed shape, not that the check passed.

    assert ["rebuild", "1"] in references

    for [function, arity] <- references do

      # Document content is repository-controlled, so minting the atom here

      # is bounded by what review admits into the runbook.

      function = String.to_atom(function)

      arity = String.to_integer(arity)

      assert Enum.any?(modules, &function_exported?(&1, function, arity)),

             "`#{function}/#{arity}` is named in #{@runbook} but no module " <>

               "the document names exports it"

    end

  end

  defp runbook, do: File.read!(@runbook)

  defp named_modules do

    Regex.scan(~r/OpenAgents(?:\.[A-Z][A-Za-z0-9_]*)+/, runbook())

    |> List.flatten()

    |> Enum.uniq()

    |> Enum.map(&Module.concat([&1]))

  end

  # `verify(…) |> IO.inspect()` calls `IO.inspect/1`, not `IO.inspect/0`, so

  # pipes are rewritten into ordinary calls before arities are read.

  defp expand_pipes(ast) do

    Macro.prewalk(ast, fn

      {:|>, _, [_, _]} = pipe ->

        [{first, _} | rest] = Macro.unpipe(pipe)

        Enum.reduce(rest, first, fn {call, position}, piped ->

          Macro.pipe(piped, call, position)

        end)

      node ->

        node

    end)

  end

  defp collect_openagents_calls(ast) do

    {_, calls} =

      Macro.prewalk(ast, [], fn

        {{:., _, [{:__aliases__, _, [:OpenAgents | _] = parts}, function]}, _, args} = node, acc

        when is_list(args) ->

          {node, [{Module.concat(parts), function, length(args)} | acc]}

        node, acc ->

          {node, acc}

      end)

    Enum.reverse(calls)

  end

end