# Forge hot loop runbook

Date: 2026-08-21

Date: 2026-08-22

Status: Active in production. The Forge loop is the default deployment path

for allowlisted code changes. Relup and rolling replacement remain fallbacks.

This is the operator procedure for the fast deployment lane: push to the owned

forge, promote, and watch a code-only change go live across the fleet in

forge, promote, and watch a compatible change go live across the fleet in

seconds without an image build. It also describes the production relup path,

the independent GitHub mirror repair worker, and the production activation

evidence.

Two consequences worth stating plainly:

- Code-only changes do **not** require an image roll once the loop is enabled;

- BEAM-only changes do **not** require an image roll once the loop is enabled;

  the whole web layer is allowlisted.

- Changes to `config/config.exs` or `config/runtime.exs` remain structural.

  The classifier must refuse them for direct loading and route them to a full

  release path.

- Changes under `priv/` remain structural because a BEAM transaction cannot

  install runtime programs, migrations, or other release-private files. The

  classifier preserves the more specific `assets_changed` and

  `migration_changed` reasons for `priv/static/` and `priv/repo/migrations/`.

  `priv/docs/` is the deliberate exception: `DocsCatalog` embeds every page as

  an external compiler resource, so its allowlisted BEAM carries the complete

  immutable documentation snapshot.

## Status reporting

| --- | --- | --- |

| Target stalls at `building`, fails `build_timeout` | No sidecar claimed the request | Check the builder container is running and the queue volume is shared |

| `needs_rolling_replace` with `structural_reasons` | Honest refusal: config, dependencies, assets, or release files changed | Try the packaged relup path; use an operator-directed image rollout when the release is incompatible |

| `needs_rolling_replace` with `release_priv_changed` | Nonembedded runtime content under `priv/` changed | Use a packaged release so every node receives the new private files; do not settle the target from a BEAM-only load |

| `needs_rolling_replace` with `off_allowlist:` reasons | The diff touched modules outside the allowlist | Widen deliberately in config, or route around the change |

| Artifact verification failure | Digest or manifest mismatch between builder and coordinator | Treat as a builder defect; inspect the retained build output |

| A node restarts mid-fleet-deploy | Membership recheck pauses phases | Boot convergence holds the node out until it converges |

# Forge transactional deployment

Date: 2026-08-20

Date: 2026-08-22

Status: Implemented locally; keep staging deployment disabled until the Gate 12 distributed staging lane exists

Status: Active in production for verified BEAM-only candidates. Use the packaged

relup or rolling-replacement lane for structural candidates.

## Purpose

changed module matches the operator-owned allowlist. Send structural changes to

the relup or rolling-replacement lanes.

The source classifier treats nonembedded release-private files under `priv/` as

structural. Direct loading cannot install those files even when the same commit

also changes an allowlisted module. `priv/docs/` is the deliberate exception:

`DocsCatalog` compiles every Markdown file into its allowlisted BEAM artifact.

## Preconditions

The coordinator refuses deployment unless all of these conditions hold:

      reasons =

        diff

        |> String.split("\n", trim: true)

        |> Enum.flat_map(&structural_reason/1)

        |> Enum.uniq()

        |> Enum.sort()

        |> classify_source_paths()

      {:ok, reasons}

    end

  end

  @doc false

  def classify_source_paths(paths) when is_list(paths) do

    paths

    |> Enum.flat_map(&structural_reason/1)

    |> Enum.uniq()

    |> Enum.sort()

  end

  defp structural_reason("mix.lock"), do: ["dependency_lock_changed"]

  defp structural_reason("mix.exs"), do: ["dependency_definition_changed"]

  defp structural_reason("Dockerfile"), do: ["runtime_image_changed"]

  defp structural_reason("assets/" <> _path), do: ["assets_changed"]

  defp structural_reason("priv/static/" <> _path), do: ["assets_changed"]

  defp structural_reason("priv/repo/migrations/" <> _path), do: ["migration_changed"]

  defp structural_reason("priv/docs/" <> _path), do: []

  defp structural_reason("priv/" <> _path), do: ["release_priv_changed"]

  defp structural_reason("rel/" <> _path), do: ["release_changed"]

  defp structural_reason("native/" <> _path), do: ["nif_changed"]

  defp structural_reason("c_src/" <> _path), do: ["nif_changed"]

  @moduledoc """

  The documentation's table of contents, and the loader for its pages.

  Pages are Markdown files under `priv/docs`, read at runtime and rendered

  through `OpenAgents.Markdown`, which is the same safe CommonMark path the

  chat surface uses. Documentation is content, not code, so it lives in files

  a writer can edit rather than in HEEx a writer cannot.

  Pages are Markdown files under `priv/docs`, embedded as one immutable

  compile-time snapshot, and rendered through `OpenAgents.Markdown`, which is

  the same safe CommonMark path the chat surface uses. Each source is an

  external compiler resource, so editing Markdown recompiles this allowlisted

  module and the Forge can deploy the complete snapshot transactionally.

  Documentation remains content that a writer can edit rather than HEEx that a

  writer cannot.

  Every page here documents something a visitor can actually reach today. A

  documentation site that describes features that do not exist is worse than

  asserts every one of them resolves in the router.

  """

  @docs_dir Path.expand("../../priv/docs", __DIR__)

  @doc_files Path.wildcard(Path.join(@docs_dir, "*.md"))

  for path <- @doc_files, do: @external_resource(path)

  @pages Map.new(@doc_files, fn path ->

           {path |> Path.basename() |> Path.rootname(), File.read!(path)}

         end)

  @sections [

    %{

      title: "Getting started",

  end

  @doc """

  Read and render one page.

  Render one page from the compiled documentation snapshot.

  Returns the rendered HTML, the headings found in it, and the Markdown source

  it came from, so a page, its table of contents, and the text the copy button

  """

  def render(slug) do

    with %{} = item <- fetch(slug),

         path = Path.join(source_dir(), "#{slug}.md"),

         {:ok, markdown} <- File.read(path) do

         {:ok, markdown} <- Map.fetch(@pages, slug) do

      toc = headings(markdown)

      # Authored prose, not a message: the source is wrapped for editing, and

      # those wraps are not line breaks the reader should see.

    assert File.read!(Path.join([cache.deps, "sample", "mix.exs"])) == "dep"

  end

  test "classifies nonembedded release-private files as structural" do

    assert BuildWorker.classify_source_paths(["priv/docs/cli-api.md"]) == []

    assert BuildWorker.classify_source_paths([

             "priv/programs/sarah/program.md",

             "priv/static/app.css",

             "priv/repo/migrations/20260822000000_add_example.exs"

           ]) == ["assets_changed", "migration_changed", "release_priv_changed"]

  end

  test "expired request IDs cannot be revived by a later attempt", context do

    expired_id = Ecto.UUID.generate()

    fresh_id = Ecto.UUID.generate()