refactor: namespace-block migration and verified audit fixes (#129)

Author: tkhquang

AGENTS.md

@@ -190,7 +190,7 @@ scripts/                 # Repo tooling (check_comment_style.py: advisory commen
   Follow the file you are in: match its established short-name convention rather than introducing a lone outlier, and do not leave a cryptic domain `a`/`r`/`c` in new code whose neighbours are spelled out.
 - **Braces:** Allman style -- opening brace on its own line for functions and classes, same line for control flow within a function body using K&R-style indented blocks. Single-statement control bodies are not required to be braced: the formatter's `InsertBraces` is intentionally left unset, so a brace-less guard clause (`if (cond) return;`) is fine; brace any multi-line or non-obvious body.
 - **Indentation:** 4 spaces, no tabs.
-- **Namespaces:** All public API lives in `namespace DetourModKit`. No `using namespace` in headers. In `.cpp` files, wrap the library's own definitions in an explicit `namespace DetourModKit { ... }` block rather than a file-scope `using namespace DetourModKit;`; the block form is the house default (the few remaining files that still open with a file-scope `using namespace DetourModKit;` are tolerated and should migrate to the block form when next touched). Every closing namespace brace must have a trailing comment: `} // namespace DetourModKit`. Implementation-only statics in `.cpp` files must be in an anonymous namespace (not a named internal namespace) to guarantee internal linkage.
+- **Namespaces:** All public API lives in `namespace DetourModKit`. No `using namespace` in headers. In `.cpp` files, wrap the library's own definitions in an explicit `namespace DetourModKit { ... }` block rather than a file-scope `using namespace DetourModKit;`; the block form is the house default and is used by every `.cpp` in the library; no translation unit opens with a file-scope `using namespace DetourModKit;`. Every closing namespace brace must have a trailing comment: `} // namespace DetourModKit`. Implementation-only statics in `.cpp` files must be in an anonymous namespace (not a named internal namespace) to guarantee internal linkage.
 - **Include guards:** All headers use `#ifndef DETOURMODKIT_<MODULE>_HPP` / `#define` / `#endif` guards (not `#pragma once`). Guard names must be prefixed with `DETOURMODKIT_` to avoid collisions with consumer projects.
 - **Includes:** Project headers use `"DetourModKit/header.hpp"`. System/external headers use `<angle brackets>`. Group: project headers, then external, then standard library.
 
@@ -390,7 +390,7 @@ These are called at 60+ fps from game hook callbacks. Never add allocations, exc
 - `Logger::log()` level check -- single atomic load
 - `Logger::log()` async enqueue -- atomic shared_ptr load + lock-free queue push
 - `Memory::is_readable()` -- sharded SRWLOCK reader + cache lookup
-- `Memory::is_readable_nonblocking()` -- try_lock_shared + cache lookup (returns Unknown on contention)
+- `Memory::is_readable_nonblocking()` -- try_lock_shared + cache lookup (returns Unknown on lock contention, a cache miss, or the init-publication window; falls back to a blocking VirtualQuery before `init_cache()`)
 - `Memory::read_ptr_unsafe()` -- SEH-protected raw dereference (MSVC), vectored-handler-guarded read on MinGW (no per-call VirtualQuery; the fault guard also closes the stale-cache dereference)
 - `Memory::read_ptr_unchecked()` -- inline pointer dereference with source and result user-mode range guards (a low-address floor plus a `USERSPACE_PTR_MAX` ceiling that rejects kernel-range and non-canonical values, which also subsumes pointer-arithmetic wraparound), no SEH (caller must guarantee structural pointer validity); debug builds add an `is_readable` assert that catches a stale or unmapped source pointer, compiled out in release so the hot path stays a single guarded memcpy
 - `Memory::seh_read<T>()` / `seh_read_bytes()` -- typed and raw SEH-guarded reads; single `__try` frame on MSVC, and on MinGW a single `rep movsb` copy under a process-wide vectored exception handler (installed lazily / by `init_cache`, removed by `shutdown_cache`) that recovers via a non-unwinding `__builtin_setjmp`/`__builtin_longjmp`, so the success path runs no syscall. Both toolchains swallow the same foreign-read fault set -- `EXCEPTION_ACCESS_VIOLATION`, `STATUS_GUARD_PAGE_VIOLATION`, and `EXCEPTION_IN_PAGE_ERROR` (a file-backed or image-mapped page failing to page in, e.g. during an RTTI / section walk) -- via the shared predicate `Memory::detail::is_guarded_read_fault`, and let any other fault continue the handler search; the MinGW handler additionally claims only faults whose address lies in the foreign range being read. A guarded read uses a single per-thread guard, so it must not nest on one thread (DMK reads are synchronous, so it does not); if `AddVectoredExceptionHandler` ever fails the reads fall back to VirtualQuery validation. Used by `Rtti` for chained RTTI walks
@@ -407,7 +407,7 @@ These are called at 60+ fps from game hook callbacks. Never add allocations, exc
 
 - **Do not modify** files under `external/` -- these are git submodules.
 - **Do not add** `using namespace` directives in header files.
-- **Prefer** an explicit `namespace DetourModKit { ... }` block over a file-scope `using namespace DetourModKit;` in `.cpp` files (the block form is the majority house style).
+- **Use** an explicit `namespace DetourModKit { ... }` block, never a file-scope `using namespace DetourModKit;`, in `.cpp` files. The block form is the house style across every translation unit.
 - **Do not add** heap allocations on hot paths (see list above).
 - **Do not break** the lock ordering documented in class headers.
 - **Do not weaken** atomic memory orderings without proving correctness.
@@ -437,4 +437,5 @@ These are called at 60+ fps from game hook callbacks. Never add allocations, exc
 - **Do not let** a queue or backlog fed at an external event rate grow without bound -- clamp the pending count to a documented ceiling (see `Input` wheel-notch `MAX_WHEEL_PENDING`).
 - **Do not let** an async/deferred sink diverge from its synchronous counterpart's configuration (timestamp format, level, etc.) -- carry the same settings through, as `Logger::enable_async_mode` does for the timestamp format.
 - **Do not open** a shared append-mode file with `GENERIC_WRITE` plus a one-time `SetFilePointer(FILE_END)` seek -- request `FILE_APPEND_DATA` so the OS positions every write at the current end of file atomically and concurrent appenders cannot interleave or overwrite each other (see `WinFileStreamBuf::open`). Truncating (`out`) mode keeps `GENERIC_WRITE` + `CREATE_ALWAYS`.
+- **Do not assume** a single `WriteFile` drains the whole request -- it can report success with `bytes_written < count` (a short write on a pipe, a near-full volume, or an interrupted write). Loop over the unwritten remainder so a buffered tail is never silently dropped, resetting the put area only after the buffer fully drains or the write hard-fails (see `WinFileStreamBuf::flush_buffer`).
 - **Do not drop** the device source when formatting an off-table input code -- a non-keyboard code must serialize in the source-tagged hex form (`Mouse:0xNN`) that `parse_input_name` reads back, or it silently round-trips to a keyboard key (see `format_input_code` / `parse_input_name`).

include/DetourModKit/async_logger.hpp

@@ -19,14 +19,23 @@
 
 namespace DetourModKit
 {
+    /// Default capacity (slot count) of the bounded MPMC message queue.
     inline constexpr size_t DEFAULT_QUEUE_CAPACITY = 8192;
+    /// Default number of messages the writer drains per write batch.
     inline constexpr size_t DEFAULT_BATCH_SIZE = 64;
+    /// Default interval between periodic writer flushes.
     inline constexpr auto DEFAULT_FLUSH_INTERVAL = std::chrono::milliseconds(100);
+    /// Maximum length, in bytes, of a single log message.
     inline constexpr size_t MAX_MESSAGE_SIZE = 16777216;
+    /// Default spin-backoff iteration count before a producer yields/parks.
     inline constexpr size_t DEFAULT_SPIN_BACKOFF_ITERATIONS = 32;
+    /// Default timeout for a blocking flush to complete.
     inline constexpr auto DEFAULT_FLUSH_TIMEOUT = std::chrono::milliseconds(500);
+    /// Byte size of one StringPool overflow block.
     inline constexpr size_t MEMORY_POOL_BLOCK_SIZE = 4096;
+    /// Number of overflow blocks the StringPool preallocates.
     inline constexpr size_t MEMORY_POOL_BLOCK_COUNT = 64;
+    /// Number of allocation slots carved from each StringPool block.
     inline constexpr size_t POOL_SLOTS_PER_BLOCK = 16;
 
     /**
@@ -116,7 +125,11 @@ namespace DetourModKit
     /**
      * @struct LogMessage
      * @brief A log entry with inline buffer optimization and overflow handling.
-     * @details Messages <= 512 bytes are stored inline. Larger messages use heap allocation via StringPool.
+     * @details Messages <= 512 bytes are stored inline. Larger messages use heap allocation via StringPool. This is a
+     *          move-only transport/value type (copy deleted, move defined) carried by value through the queue; it
+     *          keeps plain field names rather than the m_ member prefix, per the POD-struct naming convention, even
+     *          though @ref overflow is an owned heap pointer -- its lifetime is self-contained, released by reset()
+     *          and the destructor, so no class invariant rides on member encapsulation.
      */
     struct LogMessage
     {

include/DetourModKit/memory.hpp

@@ -54,14 +54,18 @@ namespace DetourModKit
         }
     }
 
-    // Maximum write size for write_bytes (64 MiB)
+    /// Maximum write size for write_bytes (64 MiB).
     inline constexpr size_t MAX_WRITE_SIZE = 64 * 1024 * 1024;
 
-    // Memory cache configuration defaults
+    /// Default number of region entries the memory cache holds.
     inline constexpr size_t DEFAULT_CACHE_SIZE = 256;
+    /// Default cache entry lifetime, in milliseconds, before a re-query.
     inline constexpr unsigned int DEFAULT_CACHE_EXPIRY_MS = 50;
+    /// Minimum permitted cache size.
     inline constexpr size_t MIN_CACHE_SIZE = 1;
+    /// Default number of cache shards, striped to reduce reader contention.
     inline constexpr size_t DEFAULT_CACHE_SHARD_COUNT = 16;
+    /// Default multiplier bounding the cache's maximum size relative to its configured size.
     inline constexpr size_t DEFAULT_MAX_CACHE_SIZE_MULTIPLIER = 2;
 
     namespace Memory
@@ -188,11 +192,18 @@ namespace DetourModKit
 
         /**
          * @brief Non-blocking readability check that avoids contention on shared locks.
-         * @details Attempts a try-lock on the cache shard. Returns Unknown if the lock cannot be acquired, allowing
-         *          callers on latency-sensitive threads to fall back to SEH instead of stalling.
+         * @details Non-blocking only once init_cache() has published the cache: it tries a shared try-lock on the
+         *          owning shard and answers from the cached protection on a hit. It returns Unknown -- so a
+         *          latency-sensitive caller can fall back to an SEH-guarded read instead of stalling -- in three
+         *          cases: the shard try-lock is contended, the shard holds no live entry for the range (a cache
+         *          miss; it does not issue a blocking VirtualQuery here), or the cache is mid-publication (the
+         *          initialized flag is set but the shard array is not yet visible). Before init_cache() (or after
+         *          shutdown_cache()) there is no cache to consult, so it falls back to a single blocking
+         *          VirtualQuery and returns a definite Readable or NotReadable, never Unknown.
          * @param address Starting address of the memory region.
          * @param size Number of bytes in the memory region to check.
-         * @return ReadableStatus indicating readable, not readable, or unknown (lock busy).
+         * @return ReadableStatus: Readable, NotReadable, or Unknown (shard lock busy, cache miss, or the
+         *         init-publication window; Unknown is only returned once the cache is initialized).
          */
         [[nodiscard]] ReadableStatus is_readable_nonblocking(const void *address, size_t size);
 

include/DetourModKit/scanner.hpp

@@ -955,12 +955,19 @@ namespace DetourModKit
          *       all-offset shape scan and additionally recognize the rarer RIP-relative shapes (`cmp [rip+d], imm`,
          *       `push [rip+d]`, a no-REX `lea`/`mov`) via a Zydis-verified sweep. Either way, a shape the active scans
          *       do not model reports NoReference rather than a guess.
+         * @note Phase 2 scans each execute-readable window from the image independently and, unlike @ref
+         *       find_pattern, carries no cross-window overlap. A RIP-relative reference whose bytes span the
+         *       boundary between two separate executable windows (a protection split inside .text, say) is decoded
+         *       in neither and reports NoReference: a fail-closed miss, never a wrong match. The common case, one
+         *       contiguous executable section, has no interior boundary.
          * @note XrefReturn::StringPointerSlot requires the unique reference to be a REX.W `lea reg, [rip+string]` and
          *       returns the effective address of the global slot the first `mov [rip+slot], reg` (same source register)
          *       within a bounded forward window stores the loaded pointer into. It resolves a cached global string
          *       pointer rather than the load site. A `mov reg, [rip+string]` load, a broad-only reference, or no
-         *       matching store reports StoreNotFound. The store match is first-within-window (compilers emit it next
-         *       to the load), not uniqueness-checked, and intervening reuse of the register is not modelled.
+         *       matching store reports StoreNotFound. The store match is first-within-window (compilers emit it
+         *       next to the load) and is not uniqueness-checked; the forward scan bails to StoreNotFound on a CALL,
+         *       on any write to the loaded register (at any width), or on a decode failure, so a clobbered or
+         *       post-call store is never misattributed.
          * @note Choose a string referenced exactly once (a long, specific literal such as a format or assert message);
          *       short, common strings are pooled and shared and will report StringAmbiguous / AmbiguousReference.
          * @note StringEncoding::Utf16le widens each query byte to a little-endian 16-bit code unit (the byte