milestone 19: hygiene sweep - dead ecs surface, single-source constants, tls classification, frontend state hazards, docker smoke network fix

src/web/handlers/mutations.zig

@@ -259,6 +259,20 @@ fn expectType(comptime name: []const u8, comptime Actual: type, comptime Expecte
 ///
 /// A state with no `reload_fn` has nothing to reload — that is the shape of a
 /// web layer under test, and of one whose composition root wired no manager.
+///
+/// Locking contract, and it is the reason every one of the fourteen call sites
+/// in `groups.zig`, `rules.zig`, `clients.zig` and `blocklists.zig` may call
+/// this *after* releasing `state.config_lock`: `reload_fn` must re-read all of
+/// the state it publishes from the database itself, under the manager's own
+/// writer lock. It must never accept rows the caller read. Rows read under
+/// `config_lock` and passed across its release are already stale, so a
+/// signature change that adds a row parameter here silently breaks the
+/// correctness of all fourteen sites — every one of them would have to move
+/// the call back inside the lock.
+///
+/// `swapLocalTables` below is the pre-read shape and is exactly the contrast:
+/// it takes the rows, so `local.zig`'s `publish` calls it while it still holds
+/// `config_lock`, and the ordering rationale lives on that function.
 pub fn reload(state: *server.WebState, io: std.Io) ?Failure {
     const reload_fn = state.reload_fn orelse return null;
     reload_fn(state, io) catch |err| {