docs: name the emulator directory by its ERTS version

remove/1's doc said the command deletes erts-<vsn>, using the same vsn as its
release-version argument. do_remove_release/4 reads erts_vsn out of the
release record and removes erts-<EVsn> only when no remaining release refers
to that emulator - and the two numbers are unrelated, normally different ones:
a release at 0.1.1 may be carrying erts-16.2. So the doc named a directory
that generally does not exist.

The same placeholder was reused in five other places where it sits beside
lib/<app>-<vsn> and so reads as the same version, including the ERTS guard's
own refusal message, which ships. All now say erts-<erts_vsn>. The synthetic
release fixture's erts-<vsn>/bin is left alone: there is no adjacent
lib/<app>-<vsn> and the version genuinely is the emulator's.

The whole-message assertion in erts_guard_test failed on the reword, which is
what it is for - the message has been wrong three times about what it can
claim, so changing it deliberately means editing that test deliberately.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ausimian

AGENTS.md

@@ -315,7 +315,7 @@ Castle's job is configuration and release management on a running node.
   library directories *relatively* — `filename:join("lib", LibName)`, so the file
   stays relocatable — so every `lib/<app>-<vsn>` the handler reads, writes or
   deletes resolves there, as does the `extract_tar(Root, Tar)` an unpack goes
-  through and the `erts-<vsn>` a removal deletes. So a Castle that wrote to
+  through and the `erts-<erts_vsn>` a removal deletes. So a Castle that wrote to
   `$RELEASE_ROOT` would put the configuration where the handler never looks, and
   an upgrade would go on using applications under the installation — a silent
   divergence in place of a loud failure. Do not "fix" the guard that way.

RELEASE.md

@@ -363,7 +363,7 @@
   the reason, rather than quietly managing the Erlang installation it happens to
   be running on. Such a release ships no emulator, so it runs the system one, and
   `code:root_dir()` — the directory `:release_handler` extracts applications
-  into, resolves every `lib/<app>-<vsn>` against, and deletes `erts-<vsn>` from —
+  into, resolves every `lib/<app>-<vsn>` against, and deletes `erts-<erts_vsn>` from —
   is then the shared Erlang installation rather than the deployment. Left to itself, `make_releases/0` created that installation's
   `releases/RELEASES`, which usually fails for want of permission and, where it
   succeeds, puts the release records of unrelated deployments in one file;

lib/castle.ex

@@ -579,8 +579,15 @@ defmodule Castle do
   Removes `vsn` from the system, and deletes what nothing else is using.
 
   `bin/castle remove <vsn>`. It takes away the version's own release directory,
-  every library directory no remaining release refers to, and the `erts-<vsn>`
-  if that version of the emulator is now unreferenced.
+  every library directory no remaining release refers to, and the
+  `erts-<erts_vsn>` of the emulator that release was built against, if no
+  remaining release still refers to it.
+
+  Note that the emulator directory is named for the *ERTS* version and not for
+  `vsn` — `do_remove_release/4` reads `erts_vsn` out of the release record and
+  compares it against the releases that are left. The two are unrelated numbers,
+  and normally different ones: a release at `0.1.1` may well be carrying
+  `erts-16.2`.
 
   It deletes rather than merely forgets, which is the point of having it: a
   deployment that never removes a superseded version only grows. Raises

lib/castle/commands.ex

@@ -165,7 +165,7 @@ defmodule Castle.Commands do
   # not Castle's choice of one - `Castle.Deployment.root_dir/0` sets out what it
   # anchors and what it does not, and is the only place that should. The half
   # this rests on is the applications: extraction, every `lib/<app>-<vsn>` the
-  # handler resolves, and the `erts-<vsn>` a removal deletes. Those cannot be
+  # handler resolves, and the `erts-<erts_vsn>` a removal deletes. Those cannot be
   # relocated, which is why relocating the *records* - the half that can be, with
   # `RELDIR` or `{sasl, releases_dir}` - is not a way out of this refusal.
   #
@@ -239,7 +239,7 @@ defmodule Castle.Commands do
     "#{refusal}: the deployment and the emulator's root are different " <>
       "directories - the deployment is #{release_root} and the emulator runs " <>
       "in #{root_dir}. That is where :release_handler extracts applications, " <>
-      "resolves every lib/<app>-<vsn> it reads, and deletes erts-<vsn> from, " <>
+      "resolves every lib/<app>-<vsn> it reads, and deletes erts-<erts_vsn> from, " <>
       "because those paths are anchored to the emulator's root rather than to " <>
       "the deployment. Pointing Castle at the deployment instead would only " <>
       "move the release records away from the applications they describe. " <>
@@ -1450,7 +1450,7 @@ defmodule Castle.Commands do
   Refuses a release that did not bring its own ERTS - see `ensure_own_erts/2` -
   and of everything gated this is the operation with the most to lose by not
   being: `remove_release/1` *deletes*, and the library directories and
-  `erts-<vsn>` it takes away are resolved against `code:root_dir()` - the anchor
+  `erts-<erts_vsn>` it takes away are resolved against `code:root_dir()` - the anchor
   nothing can relocate - so on such a deployment it is the Erlang installation
   it would be asked to delete out of.
   """

lib/castle/deployment.ex

@@ -36,7 +36,7 @@ defmodule Castle.Deployment do
   applications: the `extract_tar(Root, Tar)` an unpack goes through, every
   `lib/<app>-<vsn>` the handler resolves — stored relatively by
   `create_RELEASES/3` precisely so the file can be moved — and the
-  `erts-<vsn>` a removal deletes.
+  `erts-<erts_vsn>` a removal deletes.
 
   **The release records are not.** `init/1` takes its releases directory from
   `{sasl, releases_dir}`, then `RELDIR`, and only then `init:get_argument(root)`.

test/castle/erts_guard_test.exs

@@ -90,7 +90,7 @@ defmodule Castle.ErtsGuardTest do
                  "and the emulator's root are different directories - the deployment is " <>
                  "#{deployment} and the emulator runs in #{root_dir}. That is where " <>
                  ":release_handler extracts applications, resolves every lib/<app>-<vsn> " <>
-                 "it reads, and deletes erts-<vsn> from, because those paths are anchored " <>
+                 "it reads, and deletes erts-<erts_vsn> from, because those paths are anchored " <>
                  "to the emulator's root rather than to the deployment. Pointing Castle at " <>
                  "the deployment instead would only move the release records away from the " <>
                  "applications they describe. Relocating the records with RELDIR or the " <>