Fix data-race and disjoint-member contract comments

Three contract/implementation contradictions found in a second audit pass:

- on(DiagsTagType): @note said "reads atomic state"; _enabled is a plain
  int — corrected to describe the known data race.
- DiagsConfigState::enabled read overload: @note said "Thread-safe for
  reads"; same plain-int issue — corrected to "data race; known legacy".
- should_roll_outputlog(): @note listed reseat_diagslog() as a concurrent
  concern; the two methods operate on disjoint members (diags_log vs
  stdout_log/stderr_log) — removed the incorrect cross-reference.

Author: JosiahWI

include/tscore/DiagsTypes.h

@@ -86,8 +86,10 @@ class DiagsConfigState
   ///
   /// @param dtt DiagsTagType_Debug or DiagsTagType_Action.
   /// @return 0 if disabled, 1 if globally enabled, 2 if IP-override enabled.
-  /// @note Intended as a fast-path check. Thread-safe for reads; writes use
-  ///       the setter overload.
+  /// @note Intended as a fast-path check. The underlying storage is not
+  ///       atomic; concurrent reads and writes constitute a data race under
+  ///       the C++ memory model. This is a known legacy condition in the
+  ///       existing code. Writes use the setter overload.
   static int
   enabled(DiagsTagType dtt)
   {
@@ -98,8 +100,9 @@ class DiagsConfigState
   ///
   /// @param dtt DiagsTagType_Debug or DiagsTagType_Action.
   /// @param new_value New enabled state (0=off, 1=on, 2=override).
-  /// @post For DiagsTagType_Debug, DbgCtl's static cache is updated atomically
-  ///       so that existing DbgCtl instances reflect the change on the next check.
+  /// @post For DiagsTagType_Debug, DbgCtl's internal mode flag is updated with
+  ///       relaxed memory order so that existing DbgCtl instances reflect the
+  ///       change on the next check (no ordering guarantee with other stores).
   /// @note Not internally synchronized; call under the Diags internal lock or
   ///       during single-threaded initialization.
   static void enabled(DiagsTagType dtt, int new_value);
@@ -157,19 +160,22 @@ class Diags : public DebugInterface
 
   /// Primary diagnostics log file (e.g., diags.log).
   /// May be nullptr if no diagnostics log was configured or if the file could
-  /// not be opened at initialization. Replaced atomically under the internal
-  /// lock during log rotation and reseat operations. Do not cache this pointer
-  /// across calls that may trigger rotation.
+  /// not be opened at initialization. The pointer swap during log rotation and
+  /// reseat is performed under the internal lock, but the pre-swap reads are
+  /// not — see reseat_diagslog() and should_roll_diagslog() for the known
+  /// concurrency limitations. Do not cache this pointer.
   BaseLogFile *diags_log;
 
-  /// stdout redirect log file. Never nullptr after construction.
-  /// Replaced atomically under the internal lock during set_std_output()
-  /// and output log rolling. Do not cache this pointer.
+  /// stdout redirect log file. Initialized to a non-null value during
+  /// construction, but may be set to nullptr by set_std_output() if the
+  /// redirect target cannot be opened. The pointer swap is performed under
+  /// the internal lock. Do not cache this pointer.
   BaseLogFile *stdout_log;
 
-  /// stderr redirect log file. Never nullptr after construction.
-  /// Replaced atomically under the internal lock during set_std_output()
-  /// and output log rolling. Do not cache this pointer.
+  /// stderr redirect log file. Initialized to a non-null value during
+  /// construction, but may be set to nullptr by set_std_output() if the
+  /// redirect target cannot be opened. The pointer swap is performed under
+  /// the internal lock. Do not cache this pointer.
   BaseLogFile *stderr_log;
 
   /// Compile-time invariant constant (0x12345678). Used for debug validation.
@@ -227,7 +233,9 @@ class Diags : public DebugInterface
   /// @param mode DiagsTagType_Debug or DiagsTagType_Action.
   /// @return true if output for mode is enabled (globally or via IP override).
   /// @note This is the fast-path check. It does not perform tag matching.
-  ///       Thread-safe; reads atomic state without acquiring the internal lock.
+  ///       Does not acquire the internal lock. Reads DiagsConfigState::enabled,
+  ///       which has a known data race with concurrent writes (see
+  ///       DiagsConfigState::enabled note).
   bool
   on(DiagsTagType mode = DiagsTagType_Debug) const
   {
@@ -254,8 +262,8 @@ class Diags : public DebugInterface
   ///
   /// @param tag Tag string to match. If nullptr, returns true unconditionally.
   /// @param mode DiagsTagType_Debug or DiagsTagType_Action.
-  /// @return true if tag matches the compiled regex, or if no regex is set, or
-  ///         if tag is nullptr.
+  /// @return true if tag is nullptr, or if tag matches the compiled regex.
+  ///         false if no regex is set, or if tag does not match.
   /// @note Thread-safe. The internal lock is acquired to snapshot the regex
   ///       pointer, then released before the regex is executed.
   bool tag_activated(const char *tag, DiagsTagType mode = DiagsTagType_Debug) const;
@@ -307,17 +315,17 @@ class Diags : public DebugInterface
   /// @brief Core variadic implementation for diagnostic output.
   ///
   /// Formats and writes the message to all outputs configured for level.
-  /// Syslog writes occur after the internal lock is released.
   ///
   /// @param tag Optional tag label. May be nullptr.
   /// @param level Diagnostic severity level. Must be < DiagsLevel_Count.
   /// @param loc Optional source location. May be nullptr.
   /// @param fmt printf-style format string. Must not be nullptr.
   /// @param ap Argument list for fmt.
   /// @pre level < DiagsLevel_Count.
-  /// @post Message is written to all enabled outputs for level. Syslog, if
-  ///       configured, is written outside the internal lock.
-  /// @note Thread-safe. Acquires the internal lock for file writes.
+  /// @post Message is written to all enabled outputs for level.
+  /// @note Thread-safe. Acquires the internal lock for file writes. On most
+  ///       platforms the lock is released before syslog writes; on FreeBSD the
+  ///       lock is held across syslog as well.
   void print_va(const char *tag, DiagsLevel level, const SourceLocation *loc, const char *fmt, va_list ap) const override;
 
   /// @brief Conditionally outputs a diagnostic message if tag is enabled.
@@ -424,16 +432,17 @@ class Diags : public DebugInterface
   /// @note Thread-safe. Acquires the internal lock for the pointer reset.
   void deactivate_all(DiagsTagType mode = DiagsTagType_Debug);
 
-  /// @brief Opens blf and assigns it as the diagnostics log.
+  /// @brief Opens blf for writing.
   ///
   /// @param blf A BaseLogFile pointing to the desired log path, or nullptr
-  ///        to leave the diagnostics log unchanged.
+  ///        (treated as a no-op).
   /// @return true if blf was nullptr or was opened successfully.
   ///         false if blf could not be opened (blf is deleted and an error
   ///         is written to stderr).
   /// @pre If blf is non-null, it must not already be open.
-  /// @post On success, diags_log points to the opened blf.
-  ///       On failure, diags_log is unchanged and blf is freed.
+  /// @post On success, blf is open and ready for writes. The caller is
+  ///       responsible for assigning blf to diags_log.
+  ///       On failure, blf is freed; diags_log is unchanged.
   /// @note Thread safety: intended for single-threaded initialization.
   ///       For runtime reseat, use reseat_diagslog() instead.
   bool setup_diagslog(BaseLogFile *blf);
@@ -500,8 +509,8 @@ class Diags : public DebugInterface
   /// @return true if any output log was rolled. false otherwise.
   /// @note Pointer swaps are performed under the internal lock via
   ///       set_std_output(). File inspection (fstat, fflush) occurs outside
-  ///       the lock. Callers must ensure no concurrent set_std_output() or
-  ///       reseat_diagslog() call is in progress.
+  ///       the lock. Callers must ensure no concurrent set_std_output() call
+  ///       is in progress.
   bool should_roll_outputlog();
 
   /// @brief Redirects stdout or stderr to the specified file.