fix: require RELEASES to be consultable, not merely readable

release_handler:init/1 reads the file with file:consult/1, so a file whose
permissions are fine but whose terms are malformed fails in exactly the same
way as an unreadable one - and the hook leaves an existing file alone
whatever is in it. The message said readable, which sent an operator with a
corrupt RELEASES round the same restart loop the message exists to end.

Absent, or consultable, is the condition. Also corrects the record-check
entry higher in the release note, which still described the remedy as a bare
restart and the cause as the file not being there.

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

Author: ausimian

AGENTS.md

@@ -453,9 +453,17 @@ Castle's job is configuration and release management on a running node.
   operator told to check whether the file is "absent" or "present and unreadable"
   finds it is neither and has no applicable advice. A plain restart is exactly
   right for them. So the message asks for `releases/RELEASES` to be *absent or
-  readable* before the restart, which covers all three states and is shorter than
-  the branch it replaced. Do not turn it back into a case analysis of the cause,
-  and do not collapse it into a bare "restart the system" either.
+  consultable* before the restart, which covers all three states and is shorter
+  than the branch it replaced. Do not turn it back into a case analysis of the
+  cause, and do not collapse it into a bare "restart the system" either.
+
+  **"Consultable", not "readable".** `init/1` reads the file with
+  `file:consult/1`, so a file whose permissions are fine but whose terms are
+  malformed fails in exactly the same way, and the hook leaves an existing file
+  alone whatever is in it. An earlier version of this message said "readable" and
+  so sent an operator with a corrupt `RELEASES` round the same restart loop it was
+  written to end. Permissions are not the whole of the condition; being
+  consultable by `:release_handler` is.
 
   **And it must not name `releases/RELEASES` unqualified**, because that is the
   file the *release* creates, not necessarily the one the handler reads — see

RELEASE.md

@@ -47,16 +47,17 @@
 - `Castle.unpack/1` and `Castle.install/1` now refuse a system that cannot be
   upgraded from, and refuse it in the same call that would otherwise have done
   the work. `:release_handler` reads `releases/RELEASES` once, as it starts, and
-  when the file is not there it makes a release record up out of the boot
-  script's name and version — a record that names no applications at all.
+  when it cannot — the file absent, or there but not consultable — it makes a
+  release record up out of the boot script's name and version — a record that
+  names no applications at all.
   Upgrading a system in that state is worse than being stopped: the install
   reports success, and every application whose version changed but whose code the
   upgrade does not explicitly load goes on running its old code out of the
   directory of the release that was just replaced, until a later `remove` deletes
   it. Nothing can repair the running system afterwards, because creating the file
-  changes no record the node holds — so what the refusal says is to restart,
-  which is the one thing that does: the release creates the file before it
-  starts.
+  changes no record the node holds — so what the refusal says is to restart, with
+  the file either absent or consultable first. See *Fixed* below for what that
+  condition is and why a bare restart is not always enough.
 
   The question is asked of the node's own records rather than of the filesystem,
   which is the only way to see the case where the file exists but the boot that
@@ -70,7 +71,7 @@
   operation that *writes* release records: an unpack on such a node would put the
   made-up record into `releases/RELEASES`, where the next boot would read it back
   as though it belonged there — which takes away the restart that is the way out,
-  since the file is only created when it is missing. Committing and removing are
+  since the file is only created when it is absent. Committing and removing are
   unaffected: neither can write that record back, and refusing them could strand
   a version that was already installed.
 - `Castle.upgradable/0`, which answers the same question on its own, for an
@@ -152,13 +153,14 @@
 
 - The refusal for a system running from a synthesised release record now names a
   remedy that works. It said to restart, and a restart alone is enough only when
-  the `RELEASES` file `:release_handler` reads is absent or readable: the release
-  creates that file when it is missing, so one that is present but unreadable is
-  stepped over on every start and the system comes back on another synthesised
-  record. An operator following the old message would have restarted
+  the `RELEASES` file `:release_handler` reads is absent or consultable: it reads
+  that file with `file:consult/1`, so a malformed one fails just as an unreadable
+  one does, and the release creates the file only when it is *absent* — so
+  anything left in place that cannot be consulted is stepped over on every start
+  and the system comes back on another synthesised record. An operator following the old message would have restarted
   indefinitely.
 
-  The refusal now asks for that file to be absent or readable before the restart,
+  The refusal now asks for that file to be absent or consultable before the restart,
   and identifies it rather than assuming: `releases/RELEASES` under the release
   root, unless `RELDIR` or the `sasl` `releases_dir` parameter points elsewhere.
   Where one of those does, the two are different files and a restart cannot fix it

lib/castle/commands.ex

@@ -346,14 +346,16 @@ defmodule Castle.Commands do
            "upgrade does not load, running its old code. Creating the file now would not " <>
            "change the record this node works from, so the system has to be restarted. " <>
            "Before restarting, make sure the RELEASES file :release_handler reads is " <>
-           "either readable or absent, because the release creates that file only when it " <>
-           "is absent - an unreadable one left in place is stepped over on every start " <>
-           "and the system comes back on the same synthesised record. Absent, or " <>
-           "readable, is what a restart needs. That file is releases/RELEASES under the " <>
-           "release root unless RELDIR or the sasl releases_dir parameter points " <>
-           "elsewhere; where one of those does, the release creates a file at the root " <>
-           "that the handler will not read, so the one it does read has to be put there " <>
-           "and made readable by hand."}
+           "either absent or one it can consult - it reads that file with file:consult/1, " <>
+           "so a malformed one fails exactly as an unreadable one does, and permissions " <>
+           "are not the whole of the condition. The release creates that file only when " <>
+           "it is absent, so anything left in place that cannot be consulted is stepped " <>
+           "over on every start and the system comes back on the same synthesised " <>
+           "record. Absent, or consultable, is what a restart needs. That file is " <>
+           "releases/RELEASES under the release root unless RELDIR or the sasl " <>
+           "releases_dir parameter points elsewhere; where one of those does, the release " <>
+           "creates a file at the root that the handler will not read, so the one it does " <>
+           "read has to be put there by hand."}
 
       nil ->
         {:error, "#{refusal}: no release is running."}

test/castle/commands_test.exs

@@ -93,7 +93,7 @@ defmodule Castle.CommandsTest do
       # absence - and a case analysis of the cause, which is what this said first,
       # has no advice at all for a file that was absent at boot and has been
       # created readably since, where a plain restart is all that is needed.
-      assert message =~ "Absent, or readable, is what a restart needs."
+      assert message =~ "Absent, or consultable, is what a restart needs."
     end
 
     test "asks the release the system is running, and not another one" do