question with an answer, and `OpenAgents.Forge.Verification` computes it from

the WAL and the repository alone.

The verifier accepts either a `Repository.storage_key` or an `owner/name` path.

An `owner/name` path is resolved to a storage key through the same repository

mapping the serving path uses, and only the resolved key is checked against the

WAL. The report names both the requested path and the resolved key so an operator

sees the mapping.

The verifier accepts a repository *name* — `openagents.com`, or the

`owner/name` path a person clones — or a `Repository.storage_key`.

`OpenAgents.Forge.RepoRef` is the one place the two are told apart, and it

answers in a fixed order: a string under which the WAL holds a log is a storage

key and resolves to itself, reaching no database; anything else is a name and

is resolved through the same repository mapping the serving path uses,

namespace aliases included. Only the resolved key is checked against the WAL,

and the report names both the requested reference and the resolved key so an

operator sees the mapping.

A reference that settles on no single repository stops there, and stops with a

finding that says so: `repository_not_found`, `repository_name_ambiguous` for a

name two repositories answer to, or `repository_lookup_unavailable` when the

lookup a name needs could not be made. None of them turns the string into a

path. That is the difference this rule now carries: before it, a name went

straight into a path segment, and a name whose repository was stored under a

different key reported `wal_unreadable` — the finding that means the log is

gone — about a log that was intact. `Repos.allowed_repos/0` returns names, so

the list an operator reads before verifying is a list of references the

verifier accepts.

(Amended 2026-08-25, issue #190: the live forge's first repository is stored

under an opaque key while its configured name is `openagents.com`, so the

documented first step of rehearsal 2 verified nothing and said the log was

missing. `REPOSITORY-001`'s sentence about that repository keeping the

historical `openagents.com` key describes the migration's seed and no longer

describes the live row.)

Independence here is structural, not a promise: the WAL-and-repository check

itself reaches no database, because a verifier that queried PostgreSQL for the

detectable. The first is about replay; the second is about detection, and

neither substitutes for the other.

Evidence: `OpenAgents.Forge.Verification`, `OpenAgents.Forge.WAL`,

`OpenAgents.Forge.Repos`, and `test/openagents/forge/independence_test.exs`.

Evidence: `OpenAgents.Forge.Verification`, `OpenAgents.Forge.RepoRef`,

`OpenAgents.Forge.WAL`, `OpenAgents.Forge.Repos`,

`test/openagents/forge/independence_test.exs`, and

`test/openagents/forge/repo_ref_test.exs`.

### EXIT-003 — Recovery comes from the WAL, and the mirror is strictly lossy

### Steps

1. On the forge host, with no database available:

1. On the forge host:

   ```sh

   bin/openagents rpc 'OpenAgents.Forge.Verification.verify("{storage_key}") |> IO.inspect()'

   bin/openagents rpc 'OpenAgents.Forge.Verification.verify("OpenAgentsInc/openagents.com") |> IO.inspect()'

   ```

   The argument is the repository you clone — an `owner/name` path, or the

   name `OpenAgents.Forge.Repos.allowed_repos/0` lists.

   `OpenAgents.Forge.RepoRef` resolves it to the storage key the log is kept

   under, and the report names both, so you can see which repository was

   checked. A storage key still works and is the reference to use with no

   database available: resolving a *name* is the one step that reads the

   `repositories` table, and a key resolves against the WAL alone. A name that

   names no repository here, or two, is reported as `repository_not_found` or

   `repository_name_ambiguous` rather than checked as if it were a key

   (issue #190).

2. Expect `findings: []`. Each non-empty finding names one disagreement:

   `entry_object_missing`, `entry_digest_mismatch`, `entry_sequence_broken`,

   `served_refs_diverged`, `object_missing`, `chain_link_mismatch`, or

3. Anchor the check against a link you remember from an earlier run:

   ```sh

   bin/openagents rpc 'OpenAgents.Forge.Verification.verify("{storage_key}", anchor: %{seq: 41, link: "…"}) |> IO.inspect()'

   bin/openagents rpc 'OpenAgents.Forge.Verification.verify("OpenAgentsInc/openagents.com", anchor: %{seq: 41, link: "…"}) |> IO.inspect()'

   ```

   A rewritten prefix reports `anchor_mismatch`. Without the anchor argument

`GET /api/v1/repos/OpenAgentsInc/openagents.com/pushes` answers `200` and

serves the same head link and `chained_from` the verifier reports.

**Amended 2026-08-25 (issue #190).** Step 1 above used to say `{storage_key}`,

and the obvious value to substitute — the name

`OpenAgents.Forge.Repos.allowed_repos/0` returns, `openagents.com` — was not

one. It went into a path, the path held a bare repository that projects no log,

and the report was `wal_unreadable`: the finding that means "your write-ahead

log is missing", for a repository whose log is intact under the key

`ecd89cf6-f602-479f-9f47-266307345aaa`. `OpenAgents.Forge.RepoRef` now resolves

a name to a key before anything is read, so the step works with the name an

operator has, and a name that settles on no repository is

`repository_not_found` rather than an empty repository that looks half-alive.

The stale `openagents.com.git` bare repository on the live node is untouched by

that change: it is operator state, and removing it is an operator's decision.

The bound in this rehearsal's own preamble still holds, with one correction:

an anchor **is** published now, at

`/.well-known/openagents-forge-anchor.json`, and `GET /api/status` reports

only ref authority. PostgreSQL holds projections of it — push receipts — never

refs. A push is a receipt, not a deployment.

**Repository name and storage key** — two strings for one repository, and never

interchangeable. The **name** is what a person has: `openagents.com`, or the

`owner/name` path they clone, which is what `OpenAgents.Forge.Repos.allowed_repos/0`

lists and what a build or deploy receipt records. It is unique only inside a

namespace. The **storage key** is `Repository.storage_key`: opaque, unique

across the forge, and the single path segment the WAL keeps a log under and a

node keeps a bare repository under. Say which one you mean, and resolve a name

with `OpenAgents.Forge.RepoRef` before it reaches a path — a name is a legal

path segment, so using one as a key silently builds a directory that projects

nothing, which is what issue #190 found on the live node.

**MirrorWatch** — the component that exports accepted `main` commits from the

forge to GitHub. GitHub is a mirror only; nothing on GitHub can affect what

the forge serves.

  alias OpenAgents.{Analytics, Repositories}

  alias OpenAgents.Accounts.User

  alias OpenAgents.Forge.{GitHTTP, PushReceipt, Repos, Sync, WAL}

  alias OpenAgents.Forge.{GitHTTP, PushReceipt, RepoRef, Repos, Sync, WAL}

  alias OpenAgents.Issues.ClosingReferences

  alias OpenAgents.Repo

  alias OpenAgents.Repositories.Repository

    end

  end

  @doc "Resolve a configured repository name or storage key to its bare-cache storage key."

  def mirror_storage_key(repo) when is_binary(repo) do

    storage_key_for_storage_key(repo) || storage_key_for_name(repo) || repo

  rescue

    _database_unavailable -> repo

  end

  def mirror_storage_key(repo), do: repo

  @doc """

  Resolve a configured repository name or storage key to its bare-cache

  storage key.

  One name for the resolution every caller needs, so a name is turned into a

  key in one place: `OpenAgents.Forge.RepoRef.storage_key_or_ref/1`. A string

  that settles on no repository is returned unchanged, which is what a mirror

  push and a cache warm need — both act on a bare repository that may be keyed

  by the string itself.

  """

  def mirror_storage_key(repo), do: RepoRef.storage_key_or_ref(repo)

  @doc "Return the logical and canonical repository keys used by derived push receipts."

  def receipt_repo_keys(repo) when is_binary(repo) do

  def receipt_repo_keys(repo), do: [repo]

  defp storage_key_for_storage_key(storage_key) do

    Repo.one(

      from repository in Repository,

        where: repository.storage_key == ^storage_key,

        select: repository.storage_key

    )

  end

  defp storage_key_for_name(name) do

    Repo.one(

      from repository in Repository,

        where: repository.name == ^name,

        select: repository.storage_key

    )

  end

  defp repository_name(storage_key) when is_binary(storage_key) do

    Repo.one(

      from repository in Repository,

defmodule OpenAgents.Forge.RepoRef do

  @moduledoc """

  The one place a repository *name* becomes a repository *storage key*.

  Two different strings identify a repository here, and confusing them is what

  issue #190 was:

    * A **name** is what a person has. It is `openagents.com`, or the

      `owner/name` path they clone — `OpenAgentsInc/openagents.com`. It is what

      `OpenAgents.Forge.Repos.allowed_repos/0` lists, what a Git URL carries,

      and what `OpenAgents.Forge.Targets` records on a receipt. A name is not

      unique on its own: two namespaces can each own a repository called

      `docs`.

    * A **storage key** is what the forge keys durable state with. It is

      `Repository.storage_key`, it is unique, it is opaque — a UUID for every

      repository created since `REPOSITORY-001` — and it is the single path

      segment under which the WAL keeps a log

      (`OpenAgents.Forge.WAL`) and a node keeps its bare repository

      (`OpenAgents.Forge.Repos.bare_path/1`).

  Passing a name where a storage key belongs does not fail loudly. Both are

  strings, and a name is a legal path segment, so the forge builds a path out

  of it and finds an empty directory or nothing at all. That is how

  `Verification.verify("openagents.com")` came to report `wal_unreadable` for a

  repository whose log was intact, and how a bare repository under the *name*

  came to sit beside the one under the key.

  ## Resolution order

  `storage_key/1` answers in this order, and the order is the point:

    1. If the string is a legal storage key *and* the WAL holds a log under it,

       it is a storage key and it resolves to itself. This step reaches no

       database, so a verifier handed a key stays independent of PostgreSQL —

       `EXIT-002` — and a repository whose log predates the `repositories`

       table still resolves.

    2. Otherwise the string is treated as a name and looked up in

       `repositories`, by storage key, by `name`, or by the `owner/name` path

       the serving path resolves (`OpenAgents.Forge.GitHTTP`), namespace

       aliases included. Exactly one repository is an answer; two is

       `:ambiguous_name`, because guessing which of two repositories an

       operator meant is worse than saying the name is not enough.

    3. Otherwise `:repository_not_found`.

  A database that cannot be reached during step 2 is `:repository_lookup_unavailable`

  rather than "not found": a name whose answer is unknown must not be reported

  as a name with no answer.

  """

  import Ecto.Query

  alias OpenAgents.Forge.{Repos, WAL}

  alias OpenAgents.Repo

  alias OpenAgents.Repositories.{NamespaceAlias, Repository}

  @typedoc "What a person has: a repository `name`, or an `owner/name` path."

  @type name :: String.t()

  @typedoc """

  What the forge keys durable state with: one opaque, unique path segment.

  """

  @type storage_key :: String.t()

  @typedoc "Either of the two, before anyone has decided which it is."

  @type ref :: name() | storage_key()

  @typedoc "Why a reference names no single repository."

  @type resolution_error ::

          :repository_not_found | :ambiguous_name | :repository_lookup_unavailable

  @doc """

  The storage key `ref` names.

  Returns `{:ok, storage_key}`, or `{:error, reason}` where `reason` is one of

  the `t:resolution_error/0` values. See the module documentation for the

  order in which the two interpretations are tried.

  """

  @spec storage_key(term()) :: {:ok, storage_key()} | {:error, resolution_error()}

  def storage_key(ref) when is_binary(ref) do

    if wal_key?(ref) do

      {:ok, ref}

    else

      resolve_name(ref)

    end

  end

  def storage_key(_ref), do: {:error, :repository_not_found}

  @doc """

  The storage key `ref` names, or `ref` itself when nothing settles it.

  For the callers whose honest fallback is the string they were given: a mirror

  push and a cache warm both act on a bare repository that may well be keyed by

  the string itself, and neither is in a position to refuse. A caller that

  reports to a person should use `storage_key/1` instead, so an unresolved name

  is named as one rather than turned into a path.

  """

  @spec storage_key_or_ref(term()) :: term()

  def storage_key_or_ref(ref) when is_binary(ref) do

    case storage_key(ref) do

      {:ok, resolved} -> resolved

      {:error, _reason} -> ref

    end

  end

  def storage_key_or_ref(ref), do: ref

  # A log under this exact key is the only evidence that settles a string as a

  # storage key without asking the database anything.

  defp wal_key?(ref) do

    Repos.valid_storage_key?(ref) and match?({:ok, _generation, _index}, WAL.read_index(ref))

  end

  defp resolve_name(ref) do

    case candidate_keys(ref) do

      [storage_key] -> {:ok, storage_key}

      [] -> {:error, :repository_not_found}

      _two_or_more -> {:error, :ambiguous_name}

    end

  rescue

    _database_unavailable -> {:error, :repository_lookup_unavailable}

  end

  defp candidate_keys(ref) do

    case String.split(ref, "/") do

      [owner, name] -> owner |> path_query(name) |> keys()

      [_bare_name] -> ref |> bare_query() |> keys()

      _not_a_reference -> []

    end

  end

  defp keys(query) do

    query

    |> select([repository], repository.storage_key)

    |> limit(2)

    |> Repo.all()

    |> Enum.uniq()

  end

  # The same mapping the serving path resolves a clone URL through

  # (`OpenAgents.Forge.GitHTTP`), including renamed namespaces, so an operator

  # verifies the repository their `git clone` reached and not a different one.

  defp path_query(owner, name) do

    owner_key = String.downcase(owner)

    name_key = String.downcase(name)

    from repository in Repository,

      join: namespace in assoc(repository, :namespace),

      left_join: namespace_alias in NamespaceAlias,

      on: namespace_alias.namespace_id == namespace.id and namespace_alias.slug_key == ^owner_key,

      where:

        repository.name_key == ^name_key and

          (namespace.slug_key == ^owner_key or not is_nil(namespace_alias.id))

  end

  defp bare_query(ref) do

    name_key = String.downcase(ref)

    from repository in Repository,

      where: repository.storage_key == ^ref or repository.name_key == ^name_key

  end

end

  All git invocations are argv-only against `--git-dir`; no shell strings

  ever carry request data.

  ## Names are not storage keys

  Every function here that reaches the disk takes a **storage key** — the

  opaque, unique segment `Repository.storage_key` holds — and never a

  repository **name**. `allowed_repos/0` and `valid_name?/1` are the only two

  that speak in names, and a name is what a person has: `openagents.com`, or

  the `owner/name` path they clone.

  The two are both strings and a name is a legal path segment, so passing one

  where the other belongs builds a path rather than failing. `bare_path/1` on a

  name produces a directory beside the real repository that projects nothing —

  which is what issue #190 found on the live node. `OpenAgents.Forge.RepoRef`

  is the one place a name becomes a key; call it before calling anything here.

  """

  require Logger

  @typedoc "What a person has: a repository name, or an `owner/name` path."

  @type name :: String.t()

  @typedoc "What this module keys every path with: see `OpenAgents.Forge.RepoRef`."

  @type storage_key :: String.t()

  @name_pattern ~r/^[a-z0-9](?:[a-z0-9_-]|\.(?=[a-z0-9])){0,63}$/

  @storage_key_pattern ~r/\A[A-Za-z0-9][A-Za-z0-9._-]{0,127}\z/

      "/var/lib/openagents/forge"

  end

  @doc "Repositories this forge serves. Bounded, config-owned."

  @doc """

  Repository *names* this forge serves operationally. Bounded, config-owned.

  These are names, not storage keys: `["openagents.com"]` is the name of the

  repository whose storage key is a UUID. Resolve one with

  `OpenAgents.Forge.RepoRef.storage_key/1` before using it as a path segment.

  """

  @spec allowed_repos() :: [name()]

  def allowed_repos do

    Application.get_env(:openagents, :forge_repos, ["openagents.com"])

  end

  @doc "Whether `name` is a well-formed name this forge serves operationally."

  @spec valid_name?(term()) :: boolean()

  def valid_name?(name) when is_binary(name) do

    Regex.match?(@name_pattern, name) and name in allowed_repos()

  end

  def valid_name?(_), do: false

  @doc "Whether an opaque repository storage key is safe as one path segment."

  @doc """

  Whether an opaque repository storage key is safe as one path segment.

  Shape only. A repository name is shaped like a storage key, so this admits

  one; only `OpenAgents.Forge.RepoRef` can tell you which you are holding.

  """

  @spec valid_storage_key?(term()) :: boolean()

  def valid_storage_key?(storage_key) when is_binary(storage_key),

    do: Regex.match?(@storage_key_pattern, storage_key)

  def valid_storage_key?(_storage_key), do: false

  @doc "Absolute path of the bare repository for `repo`."

  def bare_path(repo), do: Path.join([data_dir(), "repos", repo <> ".git"])

  @doc "Absolute path of the bare repository for `storage_key`."

  @spec bare_path(storage_key()) :: String.t()

  def bare_path(storage_key), do: Path.join([data_dir(), "repos", storage_key <> ".git"])

  @doc "Delete one repository's disposable local bare-repository cache."

  @spec delete_repo(storage_key()) :: :ok | {:error, term()}

  def delete_repo(storage_key) do

    if valid_storage_key?(storage_key) do

      case File.rm_rf(bare_path(storage_key)) do

  end

  @doc "Initialize the bare repository if absent. Returns the path."

  def ensure_repo!(repo, default_branch \\ "main") do

    repo |> bare_path() |> ensure_repo_at!(default_branch)

  @spec ensure_repo!(storage_key(), String.t()) :: String.t()

  def ensure_repo!(storage_key, default_branch \\ "main") do

    storage_key |> bare_path() |> ensure_repo_at!(default_branch)

  end

  @doc false

    match?({"true" <> _rest, 0}, git(path, ["rev-parse", "--is-bare-repository"]))

  end

  def set_default_branch!(repo, default_branch) do

    repo |> bare_path() |> set_default_branch_at!(default_branch)

  @spec set_default_branch!(storage_key(), String.t()) :: :ok

  def set_default_branch!(storage_key, default_branch) do

    storage_key |> bare_path() |> set_default_branch_at!(default_branch)

  end

  @doc false

  end

  @doc "Current refs of the bare repo as a `%{name => sha}` map."

  def refs(repo) do

    repo |> bare_path() |> refs_at()

  @spec refs(storage_key()) :: %{String.t() => String.t()}

  def refs(storage_key) do

    storage_key |> bare_path() |> refs_at()

  end

  @doc false

  rollback and WAL materialization convergence). Deletes refs not present

  in the target.

  """

  def set_refs!(repo, target_refs) when is_map(target_refs) do

    repo |> bare_path() |> set_refs_at!(target_refs)

  @spec set_refs!(storage_key(), map()) :: :ok

  def set_refs!(storage_key, target_refs) when is_map(target_refs) do

    storage_key |> bare_path() |> set_refs_at!(target_refs)

  end

  @doc false

  end

  @doc "The WAL sequence this bare repo has applied (cache freshness marker)."

  def applied_seq(repo) do

    repo |> bare_path() |> applied_seq_at()

  @spec applied_seq(storage_key()) :: integer()

  def applied_seq(storage_key) do

    storage_key |> bare_path() |> applied_seq_at()

  end

  @doc false

    end

  end

  def record_applied_seq!(repo, seq) when is_integer(seq) do

    repo |> bare_path() |> record_applied_seq_at!(seq)

  @spec record_applied_seq!(storage_key(), integer()) :: :ok

  def record_applied_seq!(storage_key, seq) when is_integer(seq) do

    storage_key |> bare_path() |> record_applied_seq_at!(seq)

  end

  @doc false

  * `anchor_unreachable` — the caller supplied an anchor for a sequence this

    log does not have, or for an entry that carries no link.

  Three more findings come before any of that, because a check of the wrong

  repository is worse than no check. The caller names a repository by storage

  key or by name, `OpenAgents.Forge.RepoRef` resolves the two apart, and a

  reference that settles on no single repository stops there:

  `repository_not_found`, `repository_name_ambiguous` for a name two

  repositories answer to, and `repository_lookup_unavailable` when the lookup

  a name needs could not be made. None of them builds a path out of the string,

  which is what made an absent repository report `wal_unreadable` — the finding

  that means "your log is gone" — for a log that was never there (issue #190).

  What this cannot do is stated as plainly as what it can. Content addressing

  and the chain make tampering *evident*, not *impossible*. An operator who

  rewrites an entry, its key, the index, and every link after it produces a

  only an operator who serves something other than what was pushed.

  """

  alias OpenAgents.Forge.{ReceiptRepository, Repos, WAL}

  alias OpenAgents.Forge.{RepoRef, Repos, WAL}

  @internal_ref_prefix "refs/internal/"

  @typedoc "The verification outcome for one repository."

  @type report :: %{

          repo: String.t(),

          storage_key: String.t() | nil,

          repo: RepoRef.ref(),

          storage_key: RepoRef.storage_key() | nil,

          entries: non_neg_integer(),

          findings: [finding()],

          head: anchor() | nil,

  @doc """

  Verify one repository's served state against its WAL.

  `repo_ref` is either a storage key or a name — the `openagents.com` or

  `OpenAgentsInc/openagents.com` a person actually has. `OpenAgents.Forge.RepoRef`

  resolves the two apart, and the report names both what was asked for

  (`:repo`) and the key that was checked (`:storage_key`), so the mapping is

  visible rather than assumed. A name that names no repository, or two, is a

  finding — `repository_not_found` or `repository_name_ambiguous` — and never a

  path built out of the name, which is what made an absent repository look

  half-alive (issue #190).

  Returns `{:ok, report}` when the two agree and `{:error, report}` when they

  do not. The report always carries the findings list so a caller can render

  every disagreement, not only the first.

  `:chained_from`, the first sequence that carries a link. Entries before that

  sequence predate the chain and are not covered by it.

  """

  @spec verify(String.t(), keyword()) :: {:ok, report()} | {:error, report()}

  def verify(repo_or_path, opts \\ []) when is_binary(repo_or_path) and is_list(opts) do

    {repo, storage_key} = resolve_repo_or_path(repo_or_path)

    if is_nil(storage_key) do

      report(repo, nil, [], [finding("repository_not_found", %{"repo" => repo})])

    else

      case WAL.read_index(storage_key) do

        {:ok, _generation, index} ->

          entries = WAL.entries(index)

          findings =

            sequence_findings(entries) ++

              entry_findings(storage_key, entries) ++

              ref_findings(storage_key, index) ++

              object_findings(storage_key, entries) ++

              reachability_findings(storage_key, index) ++

              chain_findings(entries) ++

              anchor_findings(entries, normalize_anchor(opts[:anchor]))

          report(repo, storage_key, entries, findings)

        {:error, reason} ->

          report(repo, storage_key, [], [

            finding("wal_unreadable", %{"reason" => inspect(reason)})

          ])

      end

  @spec verify(RepoRef.ref(), keyword()) :: {:ok, report()} | {:error, report()}

  def verify(repo_ref, opts \\ []) when is_binary(repo_ref) and is_list(opts) do

    case RepoRef.storage_key(repo_ref) do

      {:ok, storage_key} -> verify_storage_key(repo_ref, storage_key, opts)

      {:error, reason} -> report(repo_ref, nil, [], [resolution_finding(repo_ref, reason)])

    end

  end

  defp resolve_repo_or_path(repo) when is_binary(repo) do

    if String.contains?(repo, "/") do

      case ReceiptRepository.resolve(repo) do

        %{storage_key: storage_key} -> {repo, storage_key}

        nil -> {repo, nil}

      end

    else

      {repo, repo}

  defp verify_storage_key(repo_ref, storage_key, opts) do

    case WAL.read_index(storage_key) do

      {:ok, _generation, index} ->

        entries = WAL.entries(index)

        findings =

          sequence_findings(entries) ++

            entry_findings(storage_key, entries) ++

            ref_findings(storage_key, index) ++

            object_findings(storage_key, entries) ++

            reachability_findings(storage_key, index) ++

            chain_findings(entries) ++

            anchor_findings(entries, normalize_anchor(opts[:anchor]))

        report(repo_ref, storage_key, entries, findings)

      {:error, reason} ->

        report(repo_ref, storage_key, [], [

          finding("wal_unreadable", %{"reason" => inspect(reason)})

        ])

    end

  end

  defp resolution_finding(repo_ref, :ambiguous_name),

    do: finding("repository_name_ambiguous", %{"repo" => repo_ref})

  defp resolution_finding(repo_ref, :repository_lookup_unavailable),

    do: finding("repository_lookup_unavailable", %{"repo" => repo_ref})

  defp resolution_finding(repo_ref, _not_found),

    do: finding("repository_not_found", %{"repo" => repo_ref})

  defp report(repo, storage_key, entries, findings) do

    report = %{

      repo: repo,

  inside its root before any filesystem call.

  """

  alias OpenAgents.Forge.RepoRef

  alias OpenAgents.Forge.Repos

  alias OpenAgents.Forge.Sync

    )

  end

  @doc "The forge repo the coding lane edits."

  @doc """

  The *name* of the forge repository the coding lane edits.

  A name, not a storage key: receipts and targets record this string, and

  anything that reaches the disk resolves it first with `storage_key/0`.

  """

  def repo, do: @repo

  @doc """

  The storage key the coding lane's repository is stored under.

  `repo/0` is a name and the forge keys durable state by

  `Repository.storage_key`, so the two are only the same string for a

  repository old enough to predate the split. Cloning from the name's path

  instead of the key's is how a workspace came to be cut from a bare

  repository projecting nothing (issue #190).

  """

  def storage_key, do: RepoRef.storage_key_or_ref(@repo)

  @doc "This job's clone directory (may not exist yet)."

  def workspace_dir("work-job:" <> job_id), do: Path.join(jobs_dir(), "job-" <> job_id)

    if File.dir?(Path.join(dir, ".git")) do

      {:ok, dir}

    else

      Sync.ensure_fresh(@repo)

      bare = Repos.bare_path(@repo)

      storage_key = storage_key()

      Sync.ensure_fresh(storage_key)

      bare = Repos.bare_path(storage_key)

      File.mkdir_p!(jobs_dir())

      case System.cmd("git", ["clone", "--quiet", bare, dir], stderr_to_stdout: true) do

defmodule OpenAgents.Forge.RepoRefTest do

  @moduledoc """

  Issue #190: the name a person is told to use and the key the forge stores

  under are different strings, and the verifier is the surface where confusing

  them does the most damage.

  A rehearsal reads `OpenAgents.Forge.Repos.allowed_repos/0`, gets a name, and

  runs the verifier on it. Before this, the name went straight into a path, the

  path held a bare repository projecting nothing, and the report said

  `wal_unreadable` — "your write-ahead log is gone" — about a log that was

  intact under a different key. These tests hold the name-to-key step in place

  and hold the shadow directory harmless.

  """

  use OpenAgents.DataCase, async: false

  alias OpenAgents.Forge.{CacheReadiness, RepoRef, Repos, Sync, Verification, WAL}

  @name "openagents.com"

  @owner "OpenAgentsInc"

  setup do

    Ecto.Adapters.SQL.Sandbox.mode(OpenAgents.Repo, {:shared, self()})

    root =

      Path.join(

        System.tmp_dir!(),

        "forge-repo-ref-#{System.unique_integer([:positive, :monotonic])}"

      )

    previous_data = Application.get_env(:openagents, :forge_data_dir)

    previous_wal = Application.get_env(:openagents, :forge_wal_dir)

    previous_adapter = Application.get_env(:openagents, :forge_wal_adapter)

    previous_repos = Application.get_env(:openagents, :forge_repos)

    Application.put_env(:openagents, :forge_data_dir, Path.join(root, "data"))

    Application.put_env(:openagents, :forge_wal_dir, Path.join(root, "wal"))

    Application.put_env(:openagents, :forge_wal_adapter, OpenAgents.Forge.WAL.Local)

    Application.put_env(:openagents, :forge_repos, [@name])

    CacheReadiness.reset()

    on_exit(fn ->

      restore(:forge_data_dir, previous_data)

      restore(:forge_wal_dir, previous_wal)

      restore(:forge_wal_adapter, previous_adapter)

      restore(:forge_repos, previous_repos)

      CacheReadiness.reset()

      File.rm_rf!(root)

    end)

    # Production's shape, exactly: the first repository's row has moved off the

    # historical name-as-key and onto an opaque one, while the name it is

    # cloned and configured by has not moved at all.

    storage_key = Ecto.UUID.generate()

    repository =

      OpenAgents.Repo.get_by!(OpenAgents.Repositories.Repository,

        owner_key: String.downcase(@owner),

        name_key: @name

      )

    repository

    |> Ecto.Changeset.change(storage_key: storage_key)

    |> OpenAgents.Repo.update!()

    sha = seed_wal!(root, storage_key)

    %{root: root, storage_key: storage_key, sha: sha}

  end

  describe "the name a rehearsal is handed" do

    test "verifies the repository the forge actually serves", context do

      assert {:ok, report} = Verification.verify(@name)

      assert report.repo == @name

      assert report.storage_key == context.storage_key

      assert report.entries == 1

      assert report.findings == []

    end

    test "is the name the configuration admits", context do

      # `allowed_repos/0` is the list an operator reads before verifying, so

      # what it returns has to be a reference the verifier accepts.

      assert [name] = Repos.allowed_repos()

      assert {:ok, %{storage_key: storage_key}} = Verification.verify(name)

      assert storage_key == context.storage_key

    end

    test "resolves the same through the owner/name path, in any case", context do

      assert {:ok, %{storage_key: key}} = Verification.verify("#{@owner}/#{@name}")

      assert key == context.storage_key

      assert {:ok, %{storage_key: downcased}} =

               Verification.verify("openagentsinc/#{@name}")

      assert downcased == context.storage_key

    end

    test "is not shadowed by a bare repository standing under it", context do

      # The live node carries exactly this: a bare repository under the *name*,

      # holding one ref, beside the one under the key. It is a projection of no

      # log, so it must not be able to answer for the repository.

      shadow = seed_shadow!(context.root, @name)

      refute Repos.refs_at(shadow)["refs/heads/main"] == context.sha

      assert {:ok, report} = Verification.verify(@name)

      assert report.storage_key == context.storage_key

      assert report.findings == []

      assert report.entries == 1

      # And the shadow is still there afterwards: cleaning up production state

      # is an operator's decision, not a side effect of reading it.

      assert File.dir?(shadow)

    end

  end

  describe "a reference that names no repository" do

    test "is a typed finding rather than an empty repository", _context do

      assert {:error, report} = Verification.verify("no-such-repository")

      assert report.storage_key == nil

      assert report.entries == 0

      assert [%{code: "repository_not_found", detail: %{"repo" => "no-such-repository"}}] =

               report.findings

      # The old answer. `wal_unreadable` means the log of a known repository

      # could not be read, which is a very different report from "that name is

      # not a repository here".

      refute Enum.any?(report.findings, &(&1.code == "wal_unreadable"))

    end

    test "reports an unknown owner/name path the same way", _context do

      assert {:error, report} = Verification.verify("#{@owner}/no-such-repository")

      assert report.storage_key == nil

      assert [%{code: "repository_not_found"}] = report.findings

    end

    test "reports a name two repositories answer to as ambiguous", _context do

      for owner <- ["FirstOwner", "SecondOwner"] do

        {:ok, _repository} =

          OpenAgents.Repositories.create_repository(%{

            owner: owner,

            name: "shared",

            visibility: "public",

            default_branch: "main",

            storage_key: Ecto.UUID.generate()

          })

      end

      assert {:error, %{storage_key: nil, findings: findings}} = Verification.verify("shared")

      assert [%{code: "repository_name_ambiguous", detail: %{"repo" => "shared"}}] = findings

      # Naming the owner settles it.

      assert {:error, %{storage_key: storage_key, findings: settled}} =

               Verification.verify("FirstOwner/shared")

      refute is_nil(storage_key)

      assert [%{code: "wal_unreadable"}] = settled

    end

  end

  describe "a storage key" do

    test "resolves to itself without consulting the repositories table", context do

      assert RepoRef.storage_key(context.storage_key) == {:ok, context.storage_key}

      assert {:ok, %{repo: repo, storage_key: key}} = Verification.verify(context.storage_key)

      assert repo == context.storage_key

      assert key == context.storage_key

    end

    test "resolves to itself when its log predates the repositories table", context do

      # A repository whose key is its own name and which has no row at all —

      # the shape of the forge's oldest logs. The WAL is what settles it.

      _sha = seed_wal!(context.root, "legacy-key")

      assert RepoRef.storage_key("legacy-key") == {:ok, "legacy-key"}

      assert {:ok, %{findings: [], storage_key: "legacy-key"}} = Verification.verify("legacy-key")

    end

  end

  # The live node's shadow: a bare repository under the *name*, holding one ref

  # at a commit the served repository never had, and no WAL of its own.

  defp seed_shadow!(root, name) do

    stale = Path.join(root, "stale-source")

    File.mkdir_p!(stale)

    git!(stale, ["init", "--initial-branch=main"])

    git!(stale, ["config", "user.email", "test@example.com"])

    git!(stale, ["config", "user.name", "Forge test"])

    File.write!(Path.join(stale, "README.md"), "left behind\n")

    git!(stale, ["add", "README.md"])

    git!(stale, ["commit", "-m", "A commit the served repository passed long ago"])

    shadow = Repos.ensure_repo!(name)

    {_output, 0} = Repos.git(shadow, ["fetch", stale, "main:refs/heads/main"])

    shadow

  end

  defp restore(key, nil), do: Application.delete_env(:openagents, key)

  defp restore(key, value), do: Application.put_env(:openagents, key, value)

  # One real commit, bundled, recorded as one WAL entry, materialized into the

  # bare repository the way a push would leave it.

  defp seed_wal!(root, storage_key) do

    source = Path.join(root, "source-#{storage_key}")

    File.mkdir_p!(source)

    git!(source, ["init", "--initial-branch=main"])

    git!(source, ["config", "user.email", "test@example.com"])

    git!(source, ["config", "user.name", "Forge test"])

    File.write!(Path.join(source, "README.md"), "served\n")

    git!(source, ["add", "README.md"])

    git!(source, ["commit", "-m", "Served commit"])

    sha = source |> git!(["rev-parse", "HEAD"]) |> String.trim()

    bundle = Path.join(root, "#{storage_key}.bundle")

    git!(source, ["bundle", "create", bundle, "--all"])

    {:ok, object} = WAL.put_entry_file(storage_key, 0, bundle)

    entry = %{

      "seq" => 0,

      "object" => object,

      "format" => "git_bundle",

      "refs" => %{"refs/heads/main" => sha},

      "principal" => "test:repo-ref",

      "pushed_at" => DateTime.to_iso8601(DateTime.utc_now())

    }

    {:ok, _generation} =

      WAL.cas_index(storage_key, :none, WAL.append_entry(WAL.new_index(), entry))

    :ok = Sync.ensure_fresh(storage_key)

    sha

  end

  defp git!(dir, args) do

    {output, 0} = System.cmd("git", ["-C", dir | args], stderr_to_stdout: true)

    output

  end

end