fleetd #718: pin the naming convention the poll-usage scan depends on

MessageServicePollUsageTest's messages.poll( receiver anchor only
covers a MessageService reached through a variable, field, or
parameter named "messages". Adds a second assertion in the same
class that every such declaration under src/main/java uses that
name, with its own file-walk and declaration-count controls, so a
future declaration under a different name turns this check red
instead of leaving the original scan silently blind to it.

Also tightens the Authz.permits(Principal, Action, String) javadoc
sentence to read as a plain contract statement.

fleetd/src/main/java/dev/ltms/fleet/auth/Authz.java

@@ -76,8 +76,8 @@ public final class Authz {
      * same decision {@link #NO_KNOWN_LEAD_OR_COLLABORATOR} gives explicitly. Every other action's
      * result is identical to the four-argument form's, since none of them consult the classifier.
      *
-     * <p>A test convenience, not a production entry point: its default classifier denies every
-     * collaborator, so a real gate must call the four-argument form instead.
+     * <p>Its default classifier denies every collaborator, so a caller enforcing authorization
+     * must use the four-argument form instead.
      */
     public static boolean permits(Principal caller, Action action, String targetSession) {
         return permits(caller, action, targetSession, NO_KNOWN_LEAD_OR_COLLABORATOR);

fleetd/src/test/java/dev/ltms/fleet/msg/MessageServicePollUsageTest.java

@@ -7,6 +7,8 @@ import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 import java.util.stream.Stream;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
@@ -21,6 +23,13 @@ import static org.junit.jupiter.api.Assertions.assertTrue;
  *
  * <p>This reads each file's own source text rather than reflecting on compiled bytecode, because
  * the risk is a future one-word edit at a call site, not a missing overload.
+ *
+ * <p>The scan below finds a violation by its receiver, {@code messages.poll(}, rather than the
+ * bare method name, so it does not mistake {@link java.util.Queue#poll()} for a violation. That
+ * anchor only covers a {@code MessageService} reached through a variable or field named
+ * {@code messages}, so {@link #everyMessageServiceDeclarationIsNamedMessages} pins the naming
+ * convention the anchor depends on: a declaration under any other name would be invisible to the
+ * scan above, and must turn this second check red instead of passing silently.
  */
 class MessageServicePollUsageTest {
 
@@ -30,7 +39,7 @@ class MessageServicePollUsageTest {
     void noProductionFileCallsTheSingleArgumentPollOverload() throws IOException {
         List<String> violations = new ArrayList<>();
         List<String> twoArgSites = new ArrayList<>();
-        int filesScanned = scan(PRODUCTION_SOURCE, violations, twoArgSites);
+        int filesScanned = scanForPollCalls(PRODUCTION_SOURCE, violations, twoArgSites);
 
         // CONTROL: the scan actually walked files -- a wrong root would otherwise report "no
         // violations found" having looked at nothing.
@@ -56,18 +65,122 @@ class MessageServicePollUsageTest {
                         + twoArgSites);
     }
 
-    private static int scan(Path root, List<String> violations, List<String> twoArgSites) throws IOException {
-        List<Path> files;
-        try (Stream<Path> paths = Files.walk(root)) {
-            files = paths.filter(p -> p.toString().endsWith(".java")).toList();
-        }
+    /**
+     * The {@code messages.poll(} anchor above only sees a {@code MessageService} reached through
+     * a variable, field, or parameter named {@code messages}. This asserts that every such
+     * declaration under {@code src/main/java} uses that name, so a differently named declaration
+     * -- invisible to the scan above -- fails loudly here instead of letting that scan pass on a
+     * call site it never looked at.
+     */
+    @Test
+    void everyMessageServiceDeclarationIsNamedMessages() throws IOException {
+        List<String> names = new ArrayList<>();
+        int filesScanned = scanForDeclarationNames(PRODUCTION_SOURCE, names);
+
+        // CONTROL: the scan actually walked files -- a wrong root would otherwise report "every
+        // declaration is named messages" having looked at nothing.
+        assertTrue(filesScanned > 0, "control failed: the scan under " + PRODUCTION_SOURCE
+                + " visited zero .java files -- the path is wrong, so the result below proves nothing");
+
+        // CONTROL: the declaration pattern actually finds real declarations. Zero means the
+        // pattern is broken, not that every MessageService variable, field, or parameter vanished.
+        assertTrue(names.size() > 0, "control failed: found zero MessageService declarations under "
+                + PRODUCTION_SOURCE + " -- the declaration pattern is broken, update it before "
+                + "trusting the naming check below");
+
+        List<String> other = names.stream().filter(n -> !n.equals("messages")).distinct().toList();
+        assertTrue(other.isEmpty(), "found a MessageService declaration not named \"messages\": "
+                + other + " -- the messages.poll( scan above only looks for that name, so a call "
+                + "through a differently named variable or field is invisible to it; either rename "
+                + "the declaration or widen that scan's anchor to cover it");
+    }
+
+    private static int scanForPollCalls(Path root, List<String> violations, List<String> twoArgSites)
+            throws IOException {
+        List<Path> files = javaFiles(root);
         for (Path file : files) {
-            scanFile(file, violations, twoArgSites);
+            scanFileForPollCalls(file, violations, twoArgSites);
         }
         return files.size();
     }
 
-    private static void scanFile(Path file, List<String> violations, List<String> twoArgSites) throws IOException {
+    private static int scanForDeclarationNames(Path root, List<String> names) throws IOException {
+        List<Path> files = javaFiles(root);
+        Pattern declaration = Pattern.compile("MessageService\\s+([A-Za-z_][A-Za-z0-9_]*)");
+        for (Path file : files) {
+            if (file.getFileName().toString().equals("MessageService.java")) {
+                continue; // the type's own declaration, not a caller holding a reference to it
+            }
+            String stripped = stripComments(Files.readString(file));
+            Matcher m = declaration.matcher(stripped);
+            while (m.find()) {
+                int j = m.end();
+                while (j < stripped.length() && Character.isWhitespace(stripped.charAt(j))) j++;
+                if (j < stripped.length() && stripped.charAt(j) == '(') {
+                    continue; // a method named like the convention, e.g. "MessageService messages()"
+                }
+                names.add(m.group(1));
+            }
+        }
+        return files.size();
+    }
+
+    private static List<Path> javaFiles(Path root) throws IOException {
+        try (Stream<Path> paths = Files.walk(root)) {
+            return paths.filter(p -> p.toString().endsWith(".java")).toList();
+        }
+    }
+
+    /**
+     * Replaces {@code //} and {@code /* *}{@code /} comment text with nothing, leaving code,
+     * string/char literals and line breaks untouched -- so a comment that merely mentions
+     * {@code MessageService} in prose can never be read as a declaration.
+     */
+    private static String stripComments(String source) {
+        StringBuilder out = new StringBuilder(source.length());
+        boolean inString = false;
+        boolean inChar = false;
+        int i = 0;
+        while (i < source.length()) {
+            char c = source.charAt(i);
+            if (inString) {
+                out.append(c);
+                if (c == '\\' && i + 1 < source.length()) { out.append(source.charAt(i + 1)); i += 2; continue; }
+                if (c == '"') inString = false;
+                i++;
+                continue;
+            }
+            if (inChar) {
+                out.append(c);
+                if (c == '\\' && i + 1 < source.length()) { out.append(source.charAt(i + 1)); i += 2; continue; }
+                if (c == '\'') inChar = false;
+                i++;
+                continue;
+            }
+            if (c == '"') { inString = true; out.append(c); i++; continue; }
+            if (c == '\'') { inChar = true; out.append(c); i++; continue; }
+            if (c == '/' && i + 1 < source.length() && source.charAt(i + 1) == '/') {
+                while (i < source.length() && source.charAt(i) != '\n') i++;
+                continue; // leaves the newline itself for the next iteration to append
+            }
+            if (c == '/' && i + 1 < source.length() && source.charAt(i + 1) == '*') {
+                i += 2;
+                while (i < source.length() && !(source.charAt(i) == '*' && i + 1 < source.length()
+                        && source.charAt(i + 1) == '/')) {
+                    if (source.charAt(i) == '\n') out.append('\n');
+                    i++;
+                }
+                i += 2;
+                continue;
+            }
+            out.append(c);
+            i++;
+        }
+        return out.toString();
+    }
+
+    private static void scanFileForPollCalls(Path file, List<String> violations, List<String> twoArgSites)
+            throws IOException {
         String source = Files.readString(file);
         String needle = "messages.poll(";
         int from = 0;