`OpenAgents.Forge.Pushes`, `OpenAgents.Forge.MirrorWatch`, and

`test/openagents/push_remote_contract_test.exs`.

### STACK-001 — A pull request stack is a durable object, not inferred topology

Status: Current

A stack of pull requests exists as a row, not as a reading of branch bases.

Branch topology alone is ambiguous: a branch can be based on another without

intending a stack, a retarget can be accidental, and closed pull requests

blur any inferred chain. `pull_request_stacks` carries the identity — a

repository-local number, the trunk ref, an `open`/`completed`/`dissolved`

state, and an optimistic `version` — and `pull_request_stack_entries` carries

the order: contiguous positions from 1, the boundary object ID that marks

where each layer's unique commits begin, and the observed head. Object IDs

store as raw bytes so SHA-1 and SHA-256 repositories both fit; nothing

assumes a 40-character column.

Structure is validated, not trusted. Creation requires same-repository

membership, same-repository heads, open pull requests, unique entries, unique

branches, and an unbroken direct-base chain from the trunk upward. A partial

unique index keeps a pull request in at most one active stack, and a second

partial index keeps active positions unique per stack. While a pull request

is stacked, a generic base edit fails with `stack_managed_base`; the base

belongs to the stack service.

Health is an observation and state is a lifecycle, and the two never merge.

A stack whose graph has gone stale reads `needs_rebase`, `conflicted`,

`missing_ref`, `head_changed`, `policy_blocked`, or `operation_in_progress`

while its state stays `open`. A stale graph never dissolves a stack; only an

explicit transition does, and that transition bumps the version so concurrent

operations see the change.

Evidence: `OpenAgents.Stacks`, `OpenAgents.Stacks.Stack`,

`OpenAgents.Stacks.StackEntry`, `OpenAgents.Stacks.OID`,

`ops/ci/stack-contracts.sh`, and `test/openagents/stacks_test.exs`.

## Executable proof index

This index is part of the ledger. Every `Current` invariant has at least one

| TRANSPARENCY-001 | `test/openagents/forge/visibility_test.exs`, `test/openagents/forge/browse_test.exs`, `test/openagents_web/live/code_live_test.exs` |

| REPOSITORY-001 | `test/openagents/repository_lifecycle_test.exs`, `test/openagents/repositories/provisioner_test.exs`, `test/openagents_web/controllers/repository_controller_test.exs`, `test/openagents/issues_workspace_test.exs`, `test/openagents_web/live/issue_workspace_live_test.exs`, `test/openagents_web/live/project_workspace_live_test.exs`, `test/openagents/forge/git_http_test.exs` |

| REPOSITORY-002 | `ops/ci/push-remote-check.sh`, `ops/dev/install-push-guard.sh`, `test/openagents/push_remote_contract_test.exs` |

| STACK-001 | `ops/ci/stack-contracts.sh`, `test/openagents/stacks_test.exs` |

  alias OpenAgents.Repositories

  alias OpenAgents.Repositories.Repository

  alias OpenAgents.Repositories.RepositoryPublication

  alias OpenAgents.Stacks

  alias OpenAgents.Tools.Redaction

  def list(%Repository{id: id}) do

    if pr.issue.author_user_id == actor.id or role in ~w(owner maintainer) do

      Repo.transaction(fn ->

        with {:ok, issue} <-

        with {:ok, base_attrs} <- base_update_attrs(pr, attrs),

             {:ok, issue} <-

               Issues.update_issue(

                 pr.issue,

                 Map.take(attrs, ["title", "body", "state"]),

               ),

             {:ok, updated} <-

               pr

               |> PullRequest.changeset(pull_request_update_attrs(attrs, issue.state))

               |> PullRequest.changeset(

                 Map.merge(pull_request_update_attrs(attrs, issue.state), base_attrs)

               )

               |> Repo.update() do

          %{updated | issue: issue}

        else

    end

  end

  # While a pull request is an active stack member its base belongs to the

  # stack service, so a generic base edit fails with an explanation.

  defp base_update_attrs(pr, attrs) do

    case Map.get(attrs, "base") do

      nil ->

        {:ok, %{}}

      base_ref when is_binary(base_ref) and base_ref != "" ->

        with :ok <- Stacks.ensure_base_editable(pr),

             {:ok, base_sha} <- resolve(pr.repository, base_ref) do

          {:ok, %{base_ref: base_ref, base_sha: base_sha}}

        end

      _other ->

        {:error, :invalid_ref}

    end

  end

  @doc "Opens or refreshes the draft pull request for an accepted Forge publication."

  def open_from_publication(%RepositoryPublication{} = publication, attrs, %User{} = actor) do

    publication = Repo.preload(publication, :repository)

defmodule OpenAgents.Stacks do

  @moduledoc """

  Durable pull request stacks.

  A stack is a first-class server-side object: ordered pull request entries

  with stored commit boundaries, structural validation, and health states.

  Branch topology alone stays ambiguous; the stack row is the identity.

  """

  import Ecto.Query, warn: false

  alias OpenAgents.Accounts.User

  alias OpenAgents.PullRequests.PullRequest

  alias OpenAgents.Repo

  alias OpenAgents.Repositories.Repository

  alias OpenAgents.Stacks.Stack

  alias OpenAgents.Stacks.StackEntry

  @doc """

  Creates a stack from pull requests ordered bottom to top.

  The bottom pull request's base branch becomes the stack trunk. Every later

  pull request must target the preceding pull request's head branch. All pull

  requests must be open, belong to `repository`, carry same-repository heads,

  and not already belong to an active stack.

  """

  def create(%Repository{} = repository, pull_requests, %User{} = actor)

      when is_list(pull_requests) do

    with :ok <- validate_structure(repository, pull_requests) do

      insert_with_number(repository, pull_requests, actor, 20)

    end

  end

  def get_by_number!(%Repository{id: repository_id}, number) when is_integer(number) do

    Stack

    |> Repo.get_by!(repository_id: repository_id, number: number)

    |> Repo.preload(entries: active_entries_query())

  end

  @doc "Returns the active entries of a stack ordered by position."

  def active_entries(%Stack{id: stack_id}) do

    Repo.all(from entry in active_entries_query(), where: entry.stack_id == ^stack_id)

  end

  @doc "Returns the active stack entry for a pull request, or `nil`."

  def active_entry_for_pull_request(%PullRequest{id: pull_request_id}) do

    Repo.one(

      from entry in StackEntry,

        where: entry.pull_request_id == ^pull_request_id and is_nil(entry.removed_at)

    )

  end

  @doc """

  Confirms a generic base edit may touch a pull request.

  While a pull request is an active stack member, its base branch belongs to

  the stack service; a generic edit fails with `:stack_managed_base`.

  """

  def ensure_base_editable(%PullRequest{} = pull_request) do

    case active_entry_for_pull_request(pull_request) do

      nil -> :ok

      %StackEntry{} -> {:error, :stack_managed_base}

    end

  end

  @doc """

  Records an observed health state without changing the stack state.

  Health describes the current Git graph; state describes the stack's

  lifecycle. A stale graph never dissolves a stack.

  """

  def set_health(%Stack{} = stack, health) do

    stack

    |> Stack.changeset(%{health: health})

    |> Repo.update()

  end

  @doc "Marks an open stack completed, expecting the caller's version."

  def complete(%Stack{} = stack), do: transition(stack, "completed")

  @doc "Marks an open stack dissolved, expecting the caller's version."

  def dissolve(%Stack{} = stack), do: transition(stack, "dissolved")

  defp transition(%Stack{id: id, version: version, state: "open"}, state) do

    now = DateTime.utc_now()

    {count, updated} =

      Repo.update_all(

        from(stack in Stack,

          where: stack.id == ^id and stack.version == ^version and stack.state == "open",

          select: stack

        ),

        set: [state: state, version: version + 1, updated_at: now]

      )

    case {count, updated} do

      {1, [stack]} -> {:ok, stack}

      {0, _} -> {:error, :stale_stack_version}

    end

  end

  defp transition(%Stack{}, _state), do: {:error, :stack_not_open}

  defp active_entries_query do

    from entry in StackEntry,

      where: is_nil(entry.removed_at),

      order_by: [asc: entry.position],

      preload: [pull_request: :issue]

  end

  defp validate_structure(_repository, []), do: {:error, :empty_stack}

  defp validate_structure(%Repository{id: repository_id}, pull_requests) do

    cond do

      Enum.any?(pull_requests, &(&1.repository_id != repository_id)) ->

        {:error, :repository_mismatch}

      Enum.any?(pull_requests, &(&1.head_repository_id != repository_id)) ->

        {:error, :cross_repository_head}

      Enum.any?(pull_requests, &(&1.state != "open")) ->

        {:error, :pull_request_not_open}

      duplicate?(Enum.map(pull_requests, & &1.id)) ->

        {:error, :duplicate_pull_request}

      duplicate?(branches(pull_requests)) ->

        {:error, :duplicate_branch}

      not chained?(pull_requests) ->

        {:error, :broken_base_chain}

      stacked_already?(pull_requests) ->

        {:error, :already_stacked}

      true ->

        :ok

    end

  end

  defp branches([bottom | _rest] = pull_requests) do

    [bottom.base_ref | Enum.map(pull_requests, & &1.head_ref)]

  end

  defp duplicate?(values), do: Enum.uniq(values) != values

  defp chained?(pull_requests) do

    pull_requests

    |> Enum.chunk_every(2, 1, :discard)

    |> Enum.all?(fn [lower, upper] -> upper.base_ref == lower.head_ref end)

  end

  defp stacked_already?(pull_requests) do

    ids = Enum.map(pull_requests, & &1.id)

    Repo.exists?(

      from entry in StackEntry,

        where: entry.pull_request_id in ^ids and is_nil(entry.removed_at)

    )

  end

  defp insert_with_number(_repository, _pull_requests, _actor, 0), do: {:error, :number_conflict}

  defp insert_with_number(repository, pull_requests, actor, attempts_remaining) do

    [bottom | _rest] = pull_requests

    result =

      Repo.transaction(fn ->

        number = next_number(repository.id)

        with {:ok, stack} <-

               %Stack{}

               |> Stack.changeset(%{

                 repository_id: repository.id,

                 created_by_user_id: actor.id,

                 number: number,

                 trunk_ref: bottom.base_ref

               })

               |> Repo.insert(),

             {:ok, entries} <- insert_entries(stack, pull_requests) do

          %{stack | entries: entries}

        else

          {:error, changeset} -> Repo.rollback(changeset)

        end

      end)

    case result do

      {:error, changeset} when attempts_remaining > 1 ->

        if number_conflict?(changeset) do

          insert_with_number(repository, pull_requests, actor, attempts_remaining - 1)

        else

          {:error, changeset}

        end

      other ->

        other

    end

  end

  defp insert_entries(stack, pull_requests) do

    pull_requests

    |> Enum.with_index(1)

    |> Enum.reduce_while({:ok, []}, fn {pull_request, position}, {:ok, entries} ->

      boundary =

        case entries do

          [] -> pull_request.base_sha

          [previous_entry | _] -> previous_entry.observed_head_oid

        end

      case %StackEntry{}

           |> StackEntry.changeset(%{

             stack_id: stack.id,

             pull_request_id: pull_request.id,

             position: position,

             boundary_oid: boundary,

             observed_head_oid: pull_request.head_sha

           })

           |> Repo.insert() do

        {:ok, entry} -> {:cont, {:ok, [entry | entries]}}

        {:error, changeset} -> {:halt, {:error, changeset}}

      end

    end)

    |> case do

      {:ok, entries} -> {:ok, Enum.reverse(entries)}

      {:error, changeset} -> {:error, changeset}

    end

  end

  defp next_number(repository_id) do

    max =

      Repo.one(

        from stack in Stack,

          where: stack.repository_id == ^repository_id,

          select: max(stack.number)

      )

    (max || 0) + 1

  end

  defp number_conflict?(%Ecto.Changeset{errors: errors}) do

    Enum.any?(errors, fn {_field, {_message, meta}} ->

      meta[:constraint] == :unique and

        meta[:constraint_name] == "pull_request_stacks_repository_id_number_index"

    end)

  end

  defp number_conflict?(_other), do: false

end

defmodule OpenAgents.Stacks.OID do

  @moduledoc """

  Git object ID stored as raw bytes.

  Casts lowercase hex strings for SHA-1 (40 characters) and SHA-256

  (64 characters) object names, stores the decoded 20-byte or 32-byte

  binary, and loads back to the hex string.

  """

  use Ecto.Type

  @impl true

  def type, do: :binary

  @impl true

  def cast(hex) when is_binary(hex) and byte_size(hex) in [40, 64] do

    case Base.decode16(hex, case: :lower) do

      {:ok, raw} -> {:ok, hex_from_raw(raw)}

      :error -> :error

    end

  end

  def cast(_other), do: :error

  @impl true

  def dump(hex) when is_binary(hex) and byte_size(hex) in [40, 64] do

    Base.decode16(hex, case: :lower)

  end

  def dump(_other), do: :error

  @impl true

  def load(raw) when is_binary(raw) and byte_size(raw) in [20, 32] do

    {:ok, hex_from_raw(raw)}

  end

  def load(_other), do: :error

  defp hex_from_raw(raw), do: Base.encode16(raw, case: :lower)

end

defmodule OpenAgents.Stacks.Stack do

  @moduledoc false

  use Ecto.Schema

  import Ecto.Changeset

  @primary_key {:id, :binary_id, autogenerate: true}

  @foreign_key_type :binary_id

  @states ~w(open completed dissolved)

  @healths ~w(healthy needs_rebase conflicted missing_ref head_changed policy_blocked operation_in_progress)

  schema "pull_request_stacks" do

    belongs_to :repository, OpenAgents.Repositories.Repository

    field :number, :integer

    field :trunk_ref, :string

    field :state, :string, default: "open"

    field :health, :string, default: "healthy"

    field :version, :integer, default: 1

    belongs_to :created_by_user, OpenAgents.Accounts.User

    has_many :entries, OpenAgents.Stacks.StackEntry,

      foreign_key: :stack_id,

      preload_order: [asc: :position]

    timestamps(type: :utc_datetime_usec)

  end

  def states, do: @states

  def healths, do: @healths

  def changeset(stack, attrs) do

    stack

    |> cast(attrs, [:number, :trunk_ref, :state, :health, :version])

    |> put_programmatic_change(attrs, :repository_id)

    |> put_programmatic_change(attrs, :created_by_user_id)

    |> validate_required([:repository_id, :number, :trunk_ref, :state, :health, :version])

    |> validate_length(:trunk_ref, min: 1, max: 255)

    |> validate_number(:number, greater_than_or_equal_to: 1)

    |> validate_number(:version, greater_than_or_equal_to: 1)

    |> validate_inclusion(:state, @states)

    |> validate_inclusion(:health, @healths)

    |> unique_constraint([:repository_id, :number])

    |> check_constraint(:state, name: :pull_request_stacks_state_check)

    |> check_constraint(:health, name: :pull_request_stacks_health_check)

    |> check_constraint(:version, name: :pull_request_stacks_version_check)

    |> check_constraint(:number, name: :pull_request_stacks_number_check)

    |> foreign_key_constraint(:repository_id)

  end

  defp put_programmatic_change(changeset, attrs, field) do

    case Map.fetch(attrs, field) do

      {:ok, value} -> put_change(changeset, field, value)

      :error -> changeset

    end

  end

end

defmodule OpenAgents.Stacks.StackEntry do

  @moduledoc false

  use Ecto.Schema

  import Ecto.Changeset

  @primary_key {:id, :binary_id, autogenerate: true}

  @foreign_key_type :binary_id

  schema "pull_request_stack_entries" do

    belongs_to :stack, OpenAgents.Stacks.Stack

    belongs_to :pull_request, OpenAgents.PullRequests.PullRequest

    field :position, :integer

    field :boundary_oid, OpenAgents.Stacks.OID

    field :observed_head_oid, OpenAgents.Stacks.OID

    field :removed_at, :utc_datetime_usec

    timestamps(type: :utc_datetime_usec)

  end

  def changeset(entry, attrs) do

    entry

    |> cast(attrs, [:position, :boundary_oid, :observed_head_oid, :removed_at])

    |> put_programmatic_change(attrs, :stack_id)

    |> put_programmatic_change(attrs, :pull_request_id)

    |> validate_required([

      :stack_id,

      :pull_request_id,

      :position,

      :boundary_oid,

      :observed_head_oid

    ])

    |> validate_number(:position, greater_than_or_equal_to: 1)

    |> unique_constraint([:stack_id, :position],

      name: :pull_request_stack_entries_active_position_index

    )

    |> unique_constraint(:pull_request_id,

      name: :pull_request_stack_entries_active_pull_request_index

    )

    |> check_constraint(:position, name: :pull_request_stack_entries_position_check)

    |> foreign_key_constraint(:stack_id)

    |> foreign_key_constraint(:pull_request_id)

  end

  defp put_programmatic_change(changeset, attrs, field) do

    case Map.fetch(attrs, field) do

      {:ok, value} -> put_change(changeset, field, value)

      :error -> changeset

    end

  end

end

#!/bin/sh

set -eu

script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)

repo_root=$(CDPATH= cd -- "$script_dir/../.." && pwd)

cd "$repo_root"

MIX_ENV=test mix test --warnings-as-errors \

  test/openagents/stacks_test.exs

    20260823040635,

    20260823042207,

    20260823043000,

    20260823050000

    20260823050000,

    20260823051500

  ],

  "required_tables": [

    "users",

defmodule OpenAgents.Repo.Migrations.CreatePullRequestStacks do

  use Ecto.Migration

  def change do

    create table(:pull_request_stacks, primary_key: false) do

      add :id, :binary_id, primary_key: true

      add :repository_id, references(:repositories, type: :binary_id, on_delete: :delete_all),

        null: false

      add :number, :bigint, null: false

      add :trunk_ref, :string, null: false

      add :state, :string, null: false, default: "open"

      add :health, :string, null: false, default: "healthy"

      add :version, :bigint, null: false, default: 1

      add :created_by_user_id, references(:users, type: :binary_id, on_delete: :nilify_all)

      timestamps(type: :utc_datetime_usec)

    end

    create unique_index(:pull_request_stacks, [:repository_id, :number])

    create constraint(:pull_request_stacks, :pull_request_stacks_state_check,

             check: "state IN ('open', 'completed', 'dissolved')"

           )

    create constraint(:pull_request_stacks, :pull_request_stacks_health_check,

             check:

               "health IN ('healthy', 'needs_rebase', 'conflicted', 'missing_ref', 'head_changed', 'policy_blocked', 'operation_in_progress')"

           )

    create constraint(:pull_request_stacks, :pull_request_stacks_version_check,

             check: "version >= 1"

           )

    create constraint(:pull_request_stacks, :pull_request_stacks_number_check,

             check: "number >= 1"

           )

    create table(:pull_request_stack_entries, primary_key: false) do

      add :id, :binary_id, primary_key: true

      add :stack_id,

          references(:pull_request_stacks, type: :binary_id, on_delete: :delete_all),

          null: false

      add :pull_request_id, references(:pull_requests, type: :binary_id, on_delete: :restrict),

        null: false

      add :position, :integer, null: false

      add :boundary_oid, :bytea, null: false

      add :observed_head_oid, :bytea, null: false

      add :removed_at, :utc_datetime_usec

      timestamps(type: :utc_datetime_usec)

    end

    create index(:pull_request_stack_entries, [:stack_id])

    create index(:pull_request_stack_entries, [:pull_request_id])

    create unique_index(:pull_request_stack_entries, [:stack_id, :position],

             where: "removed_at IS NULL",

             name: :pull_request_stack_entries_active_position_index

           )

    create unique_index(:pull_request_stack_entries, [:pull_request_id],

             where: "removed_at IS NULL",

             name: :pull_request_stack_entries_active_pull_request_index

           )

    create constraint(:pull_request_stack_entries, :pull_request_stack_entries_position_check,

             check: "position >= 1"

           )

    create constraint(

             :pull_request_stack_entries,

             :pull_request_stack_entries_boundary_oid_check,

             check: "octet_length(boundary_oid) IN (20, 32)"

           )

    create constraint(

             :pull_request_stack_entries,

             :pull_request_stack_entries_observed_head_oid_check,

             check: "octet_length(observed_head_oid) IN (20, 32)"

           )

  end

end

defmodule OpenAgents.StacksTest do

  use OpenAgents.DataCase

  alias OpenAgents.PullRequests

  alias OpenAgents.PullRequests.PullRequest

  alias OpenAgents.Repo

  alias OpenAgents.Stacks

  alias OpenAgents.Stacks.Stack

  alias OpenAgents.Stacks.StackEntry

  import OpenAgents.AccountsFixtures

  import OpenAgents.IssuesFixtures

  defp sha(character), do: String.duplicate(character, 40)

  defp pull_request(repository, head_ref, base_ref, attrs \\ %{}) do

    issue = issue_fixture(repository, %{title: "PR #{head_ref}"})

    defaults = %{

      repository_id: repository.id,

      issue_id: issue.id,

      head_repository_id: repository.id,

      head_ref: head_ref,

      head_sha: sha_for(head_ref),

      base_ref: base_ref,

      base_sha: sha_for(base_ref),

      state: "open"

    }

    {:ok, pull_request} =

      %PullRequest{}

      |> PullRequest.changeset(Map.merge(defaults, attrs))

      |> Repo.insert()

    pull_request

  end

  defp sha_for(ref) do

    :sha

    |> :crypto.hash(ref)

    |> Base.encode16(case: :lower)

  end

  defp chain(repository, refs) do

    refs

    |> Enum.zip(["main" | refs])

    |> Enum.map(fn {head, base} -> pull_request(repository, head, base) end)

  end

  describe "create/3" do

    test "creates a stack with contiguous entries and stored boundaries" do

      user = repository_user_fixture("stack-author")

      repository = repository_fixture()

      [bottom, middle, top] = chain(repository, ["layer-1", "layer-2", "layer-3"])

      assert {:ok, %Stack{} = stack} = Stacks.create(repository, [bottom, middle, top], user)

      assert stack.number == 1

      assert stack.trunk_ref == "main"

      assert stack.state == "open"

      assert stack.health == "healthy"

      assert stack.version == 1

      [entry_1, entry_2, entry_3] = stack.entries

      assert Enum.map(stack.entries, & &1.position) == [1, 2, 3]

      assert entry_1.boundary_oid == bottom.base_sha

      assert entry_2.boundary_oid == bottom.head_sha

      assert entry_3.boundary_oid == middle.head_sha

      assert entry_1.observed_head_oid == bottom.head_sha

      assert entry_2.observed_head_oid == middle.head_sha

      assert entry_3.observed_head_oid == top.head_sha

    end

    test "numbers are repository-local" do

      user = repository_user_fixture("stack-author")

      first_repository = repository_fixture()

      second_repository = repository_fixture()

      [first_bottom] = chain(first_repository, ["layer-1"])

      [second_bottom] = chain(second_repository, ["layer-1"])

      assert {:ok, %Stack{number: 1}} = Stacks.create(first_repository, [first_bottom], user)

      assert {:ok, %Stack{number: 1}} = Stacks.create(second_repository, [second_bottom], user)

      [next] = chain(first_repository, ["layer-2b"])

      next = %{next | base_ref: "main", base_sha: sha_for("main")}

      assert {:ok, %Stack{number: 2}} = Stacks.create(first_repository, [next], user)

    end

    test "rejects an empty stack" do

      user = repository_user_fixture("stack-author")

      repository = repository_fixture()

      assert {:error, :empty_stack} = Stacks.create(repository, [], user)

    end

    test "rejects pull requests from another repository" do

      user = repository_user_fixture("stack-author")

      repository = repository_fixture()

      other_repository = repository_fixture()

      [foreign] = chain(other_repository, ["layer-1"])

      assert {:error, :repository_mismatch} = Stacks.create(repository, [foreign], user)

    end

    test "rejects cross-repository heads" do

      user = repository_user_fixture("stack-author")

      repository = repository_fixture()

      fork = repository_fixture()

      forked =

        pull_request(repository, "layer-1", "main", %{head_repository_id: fork.id})

      assert {:error, :cross_repository_head} = Stacks.create(repository, [forked], user)

    end

    test "rejects closed pull requests" do

      user = repository_user_fixture("stack-author")

      repository = repository_fixture()

      closed = pull_request(repository, "layer-1", "main", %{state: "closed"})

      assert {:error, :pull_request_not_open} = Stacks.create(repository, [closed], user)

    end

    test "rejects duplicate pull requests" do

      user = repository_user_fixture("stack-author")

      repository = repository_fixture()

      [bottom] = chain(repository, ["layer-1"])

      assert {:error, :duplicate_pull_request} =

               Stacks.create(repository, [bottom, bottom], user)

    end

    test "rejects duplicate branches" do

      user = repository_user_fixture("stack-author")

      repository = repository_fixture()

      bottom = pull_request(repository, "layer-1", "main")

      loop = pull_request(repository, "main", "layer-1")

      assert {:error, :duplicate_branch} = Stacks.create(repository, [bottom, loop], user)

    end

    test "rejects a broken direct-base chain" do

      user = repository_user_fixture("stack-author")

      repository = repository_fixture()

      bottom = pull_request(repository, "layer-1", "main")

      detached = pull_request(repository, "layer-2", "main")

      assert {:error, :broken_base_chain} = Stacks.create(repository, [bottom, detached], user)

    end

    test "rejects a pull request that is already in an active stack" do

      user = repository_user_fixture("stack-author")

      repository = repository_fixture()

      [bottom] = chain(repository, ["layer-1"])

      assert {:ok, _stack} = Stacks.create(repository, [bottom], user)

      assert {:error, :already_stacked} = Stacks.create(repository, [bottom], user)

    end

  end

  describe "entry constraints" do

    test "one pull request belongs to at most one active stack" do

      user = repository_user_fixture("stack-author")

      repository = repository_fixture()

      [bottom] = chain(repository, ["layer-1"])

      other = pull_request(repository, "layer-x", "main")

      assert {:ok, stack} = Stacks.create(repository, [bottom], user)

      assert {:ok, other_stack} = Stacks.create(repository, [other], user)

      assert {:error, changeset} =

               %StackEntry{}

               |> StackEntry.changeset(%{

                 stack_id: other_stack.id,

                 pull_request_id: bottom.id,

                 position: 2,

                 boundary_oid: sha("a"),

                 observed_head_oid: sha("b")

               })

               |> Repo.insert()

      assert "has already been taken" in errors_on(changeset).pull_request_id

      [entry] = stack.entries

      removed_at = DateTime.utc_now()

      {:ok, _removed} = entry |> StackEntry.changeset(%{removed_at: removed_at}) |> Repo.update()

      assert {:ok, _entry} =

               %StackEntry{}

               |> StackEntry.changeset(%{

                 stack_id: other_stack.id,

                 pull_request_id: bottom.id,

                 position: 2,

                 boundary_oid: sha("a"),

                 observed_head_oid: sha("b")

               })

               |> Repo.insert()

    end

    test "active positions are unique per stack" do

      user = repository_user_fixture("stack-author")

      repository = repository_fixture()

      [bottom] = chain(repository, ["layer-1"])

      other = pull_request(repository, "layer-x", "main")

      assert {:ok, stack} = Stacks.create(repository, [bottom], user)

      assert {:error, changeset} =

               %StackEntry{}

               |> StackEntry.changeset(%{

                 stack_id: stack.id,

                 pull_request_id: other.id,

                 position: 1,

                 boundary_oid: sha("a"),

                 observed_head_oid: sha("b")

               })

               |> Repo.insert()

      assert "has already been taken" in errors_on(changeset).stack_id

    end

    test "positions start at one" do

      changeset =

        StackEntry.changeset(%StackEntry{}, %{

          stack_id: Ecto.UUID.generate(),

          pull_request_id: Ecto.UUID.generate(),

          position: 0,

          boundary_oid: sha("a"),

          observed_head_oid: sha("b")

        })

      assert "must be greater than or equal to 1" in errors_on(changeset).position

    end

    test "OIDs accept SHA-1 and SHA-256 object names and reject other values" do

      base = %{

        stack_id: Ecto.UUID.generate(),

        pull_request_id: Ecto.UUID.generate(),

        position: 1,

        observed_head_oid: sha("b")

      }

      sha256 = String.duplicate("ab", 32)

      changeset = StackEntry.changeset(%StackEntry{}, Map.put(base, :boundary_oid, sha256))

      assert Ecto.Changeset.get_field(changeset, :boundary_oid) == sha256

      for invalid <- [String.duplicate("a", 39), String.duplicate("z", 40), 42] do

        changeset = StackEntry.changeset(%StackEntry{}, Map.put(base, :boundary_oid, invalid))

        assert "is invalid" in errors_on(changeset).boundary_oid

      end

    end

    test "OIDs round-trip through the database" do

      user = repository_user_fixture("stack-author")

      repository = repository_fixture()

      [bottom] = chain(repository, ["layer-1"])

      assert {:ok, stack} = Stacks.create(repository, [bottom], user)

      [entry] = stack.entries

      reloaded = Repo.get!(StackEntry, entry.id)

      assert reloaded.boundary_oid == bottom.base_sha

      assert reloaded.observed_head_oid == bottom.head_sha

    end

  end

  describe "base edits" do

    test "generic base edits fail while a pull request is stacked" do

      user = repository_user_fixture("stack-author")

      repository = repository_with_member_fixture(user)

      [bottom] = chain(repository, ["layer-1"])

      assert :ok = Stacks.ensure_base_editable(bottom)

      assert {:ok, _stack} = Stacks.create(repository, [bottom], user)

      assert {:error, :stack_managed_base} = Stacks.ensure_base_editable(bottom)

      assert {:error, :stack_managed_base} =

               PullRequests.update(bottom, %{"base" => "other-branch"}, user)

    end

  end

  describe "health and state" do

    test "a stale graph never dissolves a stack" do

      user = repository_user_fixture("stack-author")

      repository = repository_fixture()

      [bottom] = chain(repository, ["layer-1"])

      assert {:ok, stack} = Stacks.create(repository, [bottom], user)

      assert {:ok, updated} = Stacks.set_health(stack, "needs_rebase")

      assert updated.health == "needs_rebase"

      assert updated.state == "open"

      assert updated.version == stack.version

    end

    test "rejects unknown health states" do

      user = repository_user_fixture("stack-author")

      repository = repository_fixture()

      [bottom] = chain(repository, ["layer-1"])

      assert {:ok, stack} = Stacks.create(repository, [bottom], user)

      assert {:error, changeset} = Stacks.set_health(stack, "broken")

      assert "is invalid" in errors_on(changeset).health

    end

    test "completing and dissolving bump the version and require the caller's version" do

      user = repository_user_fixture("stack-author")

      repository = repository_fixture()

      [bottom] = chain(repository, ["layer-1"])

      other = pull_request(repository, "layer-x", "main")

      assert {:ok, stack} = Stacks.create(repository, [bottom], user)

      assert {:ok, completed} = Stacks.complete(stack)

      assert completed.state == "completed"

      assert completed.version == stack.version + 1

      assert {:error, :stale_stack_version} = Stacks.complete(stack)

      assert {:error, :stack_not_open} = Stacks.dissolve(completed)

      assert {:ok, second} = Stacks.create(repository, [other], user)

      assert {:ok, dissolved} = Stacks.dissolve(second)

      assert dissolved.state == "dissolved"

      assert dissolved.version == second.version + 1

    end

    test "get_by_number!/2 returns ordered active entries" do

      user = repository_user_fixture("stack-author")

      repository = repository_fixture()

      pull_requests = chain(repository, ["layer-1", "layer-2"])

      assert {:ok, stack} = Stacks.create(repository, pull_requests, user)

      loaded = Stacks.get_by_number!(repository, stack.number)

      assert Enum.map(loaded.entries, & &1.position) == [1, 2]

      assert Enum.map(loaded.entries, & &1.pull_request.id) == Enum.map(pull_requests, & &1.id)

    end

  end

end