fix: ask for a RELEASES file the handler accepts, not one that parses

Fifth correction to one sentence, and the last, because it stops naming a
property of the file. Each earlier version gave a condition that was
necessary and not sufficient, so each admitted a narrower counterexample:
restart missed a present-but-unreadable file; absent-or-present missed one
created readably after boot; readable missed malformed terms, since init/1
reads it with file:consult/1; consultable missed a file of two valid terms,
since init/1 accepts only {ok, [Term]}. The hook leaves an existing file
alone whatever is in it, so every one of those states loops.

The remedy now asks for a file release_handler accepts, and says that no
single property of the file is the test. It cannot be narrowed again because
it claims no mechanism, and it is what an operator needs regardless: the
handler is the thing that has to take the file.

AGENTS.md records the series, so the next reader does not substitute
whichever internal criterion is current - the move that was wrong five
times.

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

Author: ausimian

AGENTS.md

@@ -457,13 +457,22 @@ Castle's job is configuration and release management on a running node.
   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.
+  **Name the authority, not the mechanism — and this is the lesson of five
+  successive corrections to one sentence.** Each named a property of the file and
+  each was necessary but not sufficient, so each admitted a narrower
+  counterexample: "restart" missed a file that was present and unreadable;
+  "present or absent" missed one created readably since boot; "readable" missed
+  malformed terms, because `init/1` reads it with `file:consult/1`; "consultable"
+  missed a file of two valid terms, because `init/1` accepts only `{ok, [Term]}`.
+  There is no reason to think that series had ended, and the hook leaves an
+  existing file alone whatever is in it, so every one of those states loops.
+
+  The message therefore asks for a file **`:release_handler` accepts**, and says
+  that no single property of the file is the test. That cannot be narrowed further
+  because it does not claim a mechanism, and it is what an operator needs anyway:
+  the handler is the thing that has to take the file. Do not "improve" it by
+  substituting whichever internal criterion is current — that is the move that was
+  wrong five times.
 
   **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,16 @@
 - `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 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.
+  when it cannot — the file absent, or there but not something it accepts — 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, with
-  the file either absent or consultable first. See *Fixed* below for what that
+  the file either absent or accepted 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,
@@ -153,14 +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 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
+  the `RELEASES` file `:release_handler` reads is absent or accepted by the handler
+  itself: present, readable and parsing as Erlang terms are each necessary and none
+  of them sufficient. The release creates the file only when it is *absent*, so
+  anything left in place that the handler will not accept 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 consultable before the restart,
+  The refusal now asks for that file to be absent or accepted 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,12 +346,14 @@ 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 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 " <>
+           "either absent or one that :release_handler itself accepts - being present, " <>
+           "being readable and parsing as Erlang terms are each necessary and none of " <>
+           "them sufficient, so the test that matters is whether the handler takes it, " <>
+           "not any one property of the file. The release creates that file only when it " <>
+           "is absent, so anything left in place that the handler will not accept is " <>
+           "stepped over on every start and the system comes back on the same " <>
+           "synthesised record. Absent, or accepted, 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 " <>

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 consultable, is what a restart needs."
+      assert message =~ "Absent, or accepted, is what a restart needs."
     end
 
     test "asks the release the system is running, and not another one" do