docs(inbound-api): DB row is authoritative for method scripts — update broken-save warning + Direct SQL Warning for the revision-checked cache

Claude-Session: https://claude.ai/code/session_01MtdgwpEeCUn6cUA5f1LMPj

src/ZB.MOM.WW.ScadaBridge.ManagementService/ManagementActor.cs

@@ -2634,9 +2634,11 @@ public class ManagementActor : ReceiveActor
         method.ReturnDefinition = cmd.ReturnDefinition;
         await repo.UpdateApiMethodAsync(method);
         await repo.SaveChangesAsync();
-        // On a compile failure the previously registered handler keeps serving — the
-        // saved-but-broken script does NOT go live. Surface that as a warning rather
-        // than a silent success (the change still persists either way).
+        // The persisted DB row is authoritative: on a compile failure the method returns
+        // a compilation error on every request (ExecuteAsync revision-checks the cached
+        // handler against the fresh row), so the saved-but-broken script does NOT keep a
+        // working version serving. Surface that as a warning rather than a silent success
+        // (the change still persists either way).
         var compileWarning = TryCompileAndDescribe(sp, method, isUpdate: true);
         await AuditAsync(sp, user, "Update", "ApiMethod", method.Id.ToString(), method.Name, method);
         return ApiMethodResult(method, compileWarning);
@@ -2657,8 +2659,10 @@ public class ManagementActor : ReceiveActor
     /// <summary>
     /// Recompiles and re-registers an inbound API method's script after a Create/Update,
     /// returning a non-null human-readable warning when the script did NOT compile. The
-    /// save is always persisted; on compile failure the previously registered handler (if
-    /// any) keeps serving requests — the broken script never replaces a working one (see
+    /// save is always persisted; the persisted DB row is authoritative, so on compile
+    /// failure the method returns a compilation error on every request (ExecuteAsync
+    /// revision-checks the cached handler against the fresh row) rather than a previously
+    /// registered handler silently continuing to serve (see
     /// <c>InboundScriptExecutor.CompileAndRegister</c>). Returns <c>null</c> when the
     /// script compiled, or when no executor is registered (e.g. a non-inbound host or a
     /// test double).
@@ -2673,7 +2677,7 @@ public class ManagementActor : ReceiveActor
 
         var detail = string.Join("; ", errors);
         return isUpdate
-            ? $"Script saved but failed to compile; the previously registered version (if any) remains active and the new script is NOT live. Compilation errors: {detail}"
+            ? $"Script saved but failed to compile; the method will return a compilation error on every request until a compiling version is saved. Compilation errors: {detail}"
             : $"Script saved but failed to compile; the method will return a compilation error until a compiling version is saved. Compilation errors: {detail}";
     }