docs: correct and harden native-core header-parsing guidance (#8)

* docs: correct and harden native-core header-parsing guidance

The C coding standards describe parsing the HWiNFO shared-memory header,
which other-language bindings will wrap, so the examples need to be
implementable as written. Several were not.

Headline fix: the §10 raw-header struct is presented with
`static_assert(sizeof == 48)` and `offsetof(...) == 0x14/0x20` checks, but
as written (no packing directive) it compiles to 56 bytes with those
offsets shifted by 4 — so all three assertions fail to compile. The real
HWiNFO layout has an *unaligned* `int64_t last_update` at byte 0x0C that
only a packed struct reproduces. Verified empirically (unpacked=56,
packed=48) and against the Python reference parser.

Changes (docs/C_CODING_STANDARDS.md):
- §10: pack the raw header struct (`#pragma pack`), fix the asserts so they
  compile and pass, add an `offsetof(last_update) == 0x0C` assert, define
  `HWI_HEADER_MAGIC = 0x53695748` to match the implementation.
- §3: new "Packed Wire Structs and Unaligned Reads" subsection — why a
  naive struct overlay mis-parses and why dereferencing an unaligned
  member is UB; read scalars via offset-based `memcpy`.
- §3: bounds-check example now honors the Review Checklist's overflow rule
  for 32-bit `size_t` (intsafe.h `SizeTMult`/`SizeTAdd`, clang-cl builtins).
- §3: `copy_fixed_string` guards `dest_size == 0` (the `dest_size - 1`
  underflow would write out of bounds).
- §9 + Appendix A: add a mockable `virtual_query` to the platform-ops table
  so the mandated region-size bound is testable; the example now sizes and
  validates the mapping before reading magic and stores `mapped_size`.
- §2/Appendix A: magic read uses unaligned-safe `memcpy`, not a typed deref.
- §4: struct-size-guard snippet uses a consistent pointer parameter + NULL
  check instead of mixing `cfg.`/`cfg->`.

SECURITY.md:
- §1.3: note the packed/unaligned header layout under the native-code
  requirements, since the bounds-validation control depends on reading the
  correct header fields.

All new/changed C snippets compile clean under `-Wall -Wextra -Wconversion
-Wshadow` with the layout assertions passing.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: address review — mock virtual_query, naming, self-contained snippets

Round-2 review feedback from @lcj-codex-reviewer, @lcj-claude-reviewer,
@lcj-kimi-coder, and Copilot.

- §9 (main fix): the worked mock test left `hwi_platform.virtual_query`
  pointing at the real `VirtualQuery`, so after Appendix A started calling it
  the example invoked a real Win32 syscall on a malloc'd blob and never
  demonstrated the bound it was added to enable. Add `mock_virtual_query`
  (test-controlled `RegionSize` via `will_return`), wire it into
  `test_parse_valid_shm`, and add `test_open_rejects_undersized_region`
  asserting `HWI_ERR_CORRUPT_DATA` for a sub-header mapping.
- §3: align the bounds/overflow/pointer-arith examples to the Section 10
  struct field names (`sensor_section_offset`, `sensor_element_count`,
  `sensor_element_size`) so they map onto the real header 1:1.
- §3: note that `FAILED()` comes from `<windows.h>` (via `<winerror.h>`),
  not `<intsafe.h>` alone.
- §10: add `#include <stdint.h>` and clarify that `static_assert` is a
  standard `<assert.h>` macro since C11/C17, so the snippet is self-contained.

The new mock/bound logic compiles clean under `-Wall -Wextra -Wconversion
-Wshadow` and behaves as asserted (valid region -> HWI_OK, undersized ->
HWI_ERR_CORRUPT_DATA).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: pin cmocka 2.0.2 in the test example

Per maintainer preference. Keeps the accurate attribution (the 2.0 line —
2.0.0, December 2025 — introduced the C99 requirement and TAP 14 support)
while pinning the 2.0.2 patch release in the FetchContent tag.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: make the mock test example fully hermetic + copyability nits

Round-3 review feedback from @lcj-codex-reviewer and Copilot.

- §9 (Codex): both tests left `unmap_view_of_file` / `close_handle` wired to
  the real Win32 default table, so the success path (`hwi_session_close`) and
  the undersized-region goto-cleanup path called real `UnmapViewOfFile` /
  `CloseHandle` on fake state ((HANDLE)0xDEAD, a heap/stack buffer). Add no-op
  `mock_unmap_view_of_file` / `mock_close_handle` and wire them into both
  tests so the example is fully hermetic.
- §9 (Copilot): `mock_virtual_query` documented a 0-on-failure contract it
  didn't implement and would deref a NULL/undersized `mbi`. Add the
  `mbi == NULL || mbi_size < sizeof(*mbi)` guard.
- §3 (Copilot + @lcj-claude-reviewer): the overflow prose still said
  `sensor_count * sensor_size`; renamed to `sensor_element_count *
  sensor_element_size` to match the code and the §10 struct.
- §3 (Copilot): the "Good"/"Bad" pointer-arith snippet declared `sensor_i`
  twice in one scope (a redeclaration error if copied); renamed the "Bad"
  one to `sensor_i_bad`.

Updated mocks compile clean under `-Wall -Wextra -Wconversion -Wshadow`
(success -> sizeof(mbi); NULL/undersized buffer -> 0; no-op cleanup -> TRUE).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: add explicit return to the hwi_configure example

Round-4 (Copilot): the §4 struct-size-guard example returned hwi_error_t but
fell off the end after the success-path comment, which trips -Wreturn-type
(and is UB if the return value is used) — at odds with the doc's own /WX
policy. Add the missing `return HWI_OK;`. Verified warning-free under
-Wall -Wextra -Wconversion -Wshadow -Wreturn-type.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Coder <lcj.claude.code@pm.me>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>