docs: S23.22 give every documented fact one home, and check it stays there

.github/workflows/ci.yml

@@ -772,6 +772,16 @@ jobs:
         with:
           persist-credentials: false
 
+      # Platforms are declared in SOLIDSYSLOG_PLATFORM_REGISTRY and roles by
+      # their Core/Interface/SolidSyslog<Role>Definition.h header. This asserts
+      # the docs enumerate exactly what the code declares — a platform's pages,
+      # nav entry, description and matrix row; a role's link from the porting
+      # guide, the roles index and the nav — and the reverse in both cases. It
+      # also holds the two boundaries hand review kept losing: no platform names
+      # another, and every class a platform ships is on its page.
+      - name: Check the docs match what the code declares
+        run: python3 scripts/check_platform_docs.py
+
       # Guard the build hooks against regression — the source-link rewrite's
       # Markdown parsing, and the meta-description map's nav validation.
       # Image digest below is mkdocs-mkdoxy sha-34173c0 (see docs/containers.md).

Bdd/Targets/FreeRtosLwip/README.md

@@ -64,7 +64,7 @@ so the resolve completes on-device without a DNS server.
 > timeout branches are unit-tested in
 > `Tests/Lwip/SolidSyslogLwipRawDnsResolverTest`, consistent with the project's
 > integration-over-BDD stance for paths the harness can't realistically drive.
-> See [`docs/integrating-lwip.md`](../../../docs/integrating-lwip.md#dns).
+> See [lwIP setup — DNS](../../../docs/platforms/lwipraw/setup.md#dns).
 
 ## Build
 

Bdd/features/mtls_transport.feature

@@ -1,10 +1,10 @@
 @mtls
 Feature: Mutual TLS message delivery
   The BDD target authenticates itself to the oracle with a client
-  certificate over RFC 5425 TLS, exercising mTLS end-to-end. Satisfies
-  IEC 62443 CR 2.12 (non-repudiation, SL3+) — mutual TLS cryptographically
-  identifies the sender, while the SIEM detects sequence gaps. Cross-platform: Linux runner uses syslog-ng,
-  Windows runner uses otelcol-contrib with client_ca_file.
+  certificate over RFC 5425 TLS, exercising mTLS end-to-end. Mutual TLS
+  cryptographically identifies the sender, while the SIEM detects sequence
+  gaps. Cross-platform: Linux runner uses syslog-ng, Windows runner uses
+  otelcol-contrib with client_ca_file.
 
   Scenario: Message delivered over mutual TLS
     Given the syslog oracle is running

CLAUDE.md

@@ -41,7 +41,7 @@ what matters — it becomes the permanent commit message on `main` on squash mer
 **Branch protection rules (configured on GitHub):**
 
 - Direct pushes to `main` are blocked
-- PRs require all status checks to pass before merging: CodeQL, analyze-codeql, analyze-cppcheck, analyze-format, analyze-iwyu, analyze-iwyu-freertos-lwip, analyze-iwyu-freertos-plustcp, analyze-markdown, analyze-tidy, analyze-tidy-freertos-lwip, analyze-tidy-freertos-plustcp, bdd-freertos-qemu-lwip, bdd-freertos-qemu-plustcp, bdd-linux-syslog-ng, bdd-windows-otel, build-freertos-host-tdd-plustcp, build-freertos-target-lwip, build-freertos-target-plustcp, build-linux-clang, build-linux-gcc, build-linux-tunable-override, build-windows-msvc, consumer-smoke-freertos-cross, consumer-smoke-linux, coverage-linux-gcc, docs-build, integration-linux-mbedtls, integration-linux-openssl, integration-windows-openssl, sanitize-linux-gcc, summary, verify-manifest
+- PRs require all status checks to pass before merging: CodeQL, analyze-codeql, analyze-cppcheck, analyze-format, analyze-iwyu, analyze-iwyu-freertos-lwip, analyze-iwyu-freertos-plustcp, analyze-markdown, analyze-tidy, analyze-tidy-freertos-lwip, analyze-tidy-freertos-plustcp, bdd-freertos-qemu-lwip, bdd-freertos-qemu-plustcp, bdd-linux-syslog-ng, bdd-windows-otel, build-freertos-host-tdd-plustcp, build-freertos-target-lwip, build-freertos-target-plustcp, build-linux-c89-headers, build-linux-c99, build-linux-clang, build-linux-gcc, build-linux-tunable-override, build-windows-msvc, consumer-smoke-freertos-cross, consumer-smoke-linux, coverage-linux-gcc, docs-build, integration-linux-mbedtls, integration-linux-openssl, integration-windows-openssl, sanitize-linux-gcc, summary, verify-manifest
 - The `analyze-iwyu*` lanes run `continue-on-error: true` — they are required contexts but advisory in substance, so they report success whatever IWYU finds
 - Code scanning contributes two contexts and both are required. `analyze-codeql` is the Actions job in `codeql.yml`, and proves the analysis ran; `CodeQL` is the code-scanning results check, and is the one that fails when a PR introduces a new alert. Requiring only the job would let a PR add findings and still merge green
 - Feeding the `summary` aggregator does **not** make a lane blocking. `summary` is declared `if: always()` and asserts nothing about `needs.*.result`, so a new lane gates merges only once its own context is added to the required list above
@@ -427,7 +427,7 @@ Core headers live under `Core/Interface/`; each platform pack puts its own under
 **Each header's `@file` brief is the authoritative description of what it provides and
 why.** Read the header rather than a copy of it. For the wider map:
 
-- `docs/roles/index.md` — the twelve roles, each with its vtable contract and the backends
+- `docs/roles/index.md` — the roles, each with its vtable contract and the backends
   that realise it.
 - `docs/platforms/*.md` — what each platform pack supplies.
 - `docs/api-reference/` plus the generated Doxygen indexes (`docs/api/files.md`,
@@ -500,10 +500,10 @@ format-on-save:
 
 - **`InsertBraces: true`** combined with `AllowShortIfStatementsOnASingleLine: Never`,
   `AllowShortLoopsOnASingleLine: false`, `AllowShortFunctionsOnASingleLine: None`, and
-  `AllowShortBlocksOnASingleLine: Never` — formatter-side enforcement of **MISRA 15.6**
-  (the body of an iteration- or selection-statement shall be a compound-statement). clang-format
-  rewrites your code to add the braces if they are missing, and the `AllowShort*` settings
-  stop them being collapsed back onto a single line.
+  `AllowShortBlocksOnASingleLine: Never` — formatter-side enforcement of **MISRA 15.6**,
+  which is why every `if`, `else`, `for` and `while` body in this project is braced.
+  clang-format rewrites your code to add the braces if they are missing, and the
+  `AllowShort*` settings stop them being collapsed back onto a single line.
 - **`RemoveParentheses: Leave`** — keeps the project **MISRA 12.1 safe**. The advisory rule
   prefers explicit precedence parentheses; flipping this to `MultipleParentheses` would let
   clang-format strip them.
@@ -513,6 +513,58 @@ See `docs/misra-deviations.md` for the project's stance on MISRA conformance.
 
 ---
 
+## Documentation
+
+Three rules, and they matter more than anything about wording. A wrong claim
+costs one edit to fix; a wrong claim that has been copied costs an audit of
+every page to find, and the copies rot silently because nothing checks them.
+
+### Verify before asserting
+
+Every statement about what the code does is read out of the code, not inferred
+from a name, a neighbouring document, or something written earlier in the same
+session. This is absolute for **failure modes**: before writing that something
+fails, degrades, is silent, or is not reported, open the function and confirm
+it. Claims that an error is *not* reported are the ones most often wrong, and
+the most damaging, because they push an integrator into defending against a
+problem that does not exist.
+
+A document that is already in the repository is not evidence. It may be the
+thing that is wrong.
+
+### One claim, one place
+
+Every fact has exactly one home. Everywhere else links to it, or omits it.
+
+| The fact | Its home |
+|---|---|
+| What a config field or parameter means, including its edge values | the doc comment on that field |
+| What a role's contract requires | that role's `SolidSyslog<Role>Definition.h` |
+| What a platform ships, needs, guarantees, and leaves to the integrator | that platform's page under `docs/platforms/<slug>/` |
+| How to wire a platform, and what will catch you out | that platform's `setup.md` |
+| What Core does | the Core headers; `docs/core/index.md` curates and links them |
+| How to get it building | `docs/build-integration.md` |
+
+Writing the same sentence on a second page is the signal that it belongs on
+neither — find its home, put it there once, and link. Do not restate a fact to
+make a page self-contained: self-contained pages are how a set of documents
+drifts out of agreement with itself.
+
+This applies with particular force to the compliance guides, which attract
+detail they should not hold. `docs/iec62443.md` is a quick reference that
+reassures a developer or a security officer that the library can meet their
+needs. It is **not** an audit artefact, and it is not a place to gather role
+behaviour, platform behaviour, or catalogues of failure modes.
+
+### A platform page never describes another platform
+
+Naming a second platform to contrast behaviour, or to say where a capability
+comes from, couples the two: the eleventh platform then has to be added to ten
+pages. State this platform's own behaviour completely, and point at the
+capability matrix in `docs/platforms/index.md` for who fills what.
+
+---
+
 ## Design Patterns
 
 These patterns are re-affirmed each time we do a code-hygiene pass. New

CMakeLists.txt

@@ -47,8 +47,8 @@ if(SOLIDSYSLOG_IS_TOP_LEVEL)
 endif()
 
 # Default to C11 (for the optional C11 atomics counter), but let an externally
-# supplied standard win so the pre-release C99 portability check can build the
-# library at -std=c99 without editing this file. See docs/local-checks.md.
+# supplied standard win so the `c99` preset can build the library at -std=c99
+# without editing this file. See docs/builds.md.
 if(NOT DEFINED CMAKE_C_STANDARD)
     set(CMAKE_C_STANDARD 11)
 endif()

Core/Interface/SolidSyslogStreamDefinition.h

@@ -17,15 +17,29 @@ SOLIDSYSLOG_EXTERN_C_BEGIN
 
     /** The contract a byte-stream transport (TCP, TLS over TCP) fills in; the
      *  library drives it from the servicing pass, so it need not be reentrant.
-     *  Each slot's semantics are the corresponding SolidSyslogStream_* function
-     *  in SolidSyslogStream.h; an implementer must honour them, notably the
-     *  non-blocking bounded behaviour and the close-on-failure lifecycle that
-     *  lets the caller reconnect with a bare Open. */
+     *  What a caller may expect of each call is documented on the corresponding
+     *  SolidSyslogStream_* function in SolidSyslogStream.h; what follows is the
+     *  same contract as obligations on the implementer. */
     struct SolidSyslogStream
     {
+        /** Bound the connect, and any handshake above it. One servicing pass
+         *  drives every sender, so a connect that blocks stalls the whole drain,
+         *  not just this stream. Leave nothing open on a failed path: the caller
+         *  retries with a bare Open and never calls Close first. */
         bool (*Open)(struct SolidSyslogStream* base, const struct SolidSyslogAddress* addr);
+        /** All-or-nothing. Never report a partial write as success — the record
+         *  is gone from the caller's hands once you return true. If the whole
+         *  buffer cannot go, close internally and return false; the caller
+         *  reopens and store-and-forward replays. */
         bool (*Send)(struct SolidSyslogStream* base, const void* buffer, size_t size);
+        /** Return 0 when nothing is available, never a negative — the two are
+         *  acted on differently, and a would-block reported as an error costs a
+         *  reconnect on an idle link. Reserve the negative return for a real
+         *  teardown, and close internally before making it. */
         SolidSyslogSsize (*Read)(struct SolidSyslogStream* base, void* buffer, size_t size);
+        /** Idempotent, and leaves the instance reusable — a later Open
+         *  reconnects it. Called on a stream that is already closed, on one that
+         *  never opened, and again from Destroy. */
         void (*Close)(struct SolidSyslogStream* base);
     };
 

Core/Source/SolidSyslogMacros.h

@@ -1,10 +1,10 @@
 #ifndef SOLIDSYSLOGMACROS_H
 #define SOLIDSYSLOGMACROS_H
 
-/* Compile-time assertion. C++ and C11 have native primitives that carry the
-   message into the diagnostic; a strict C99 toolchain — the optional
-   portability target, exercised by the pre-release `c99` preset (see
-   docs/local-checks.md) — has neither, so it falls back to declaring an array
+/* Compile-time assertion. C++11 and C11 have native primitives that carry the
+   message into the diagnostic; a strict C99 toolchain — the conformance
+   baseline, built on every pull request by the `build-linux-c99` lane (see
+   docs/builds.md) — has neither, so it falls back to declaring an array
    whose length goes negative (a constraint violation every C99 compiler
    rejects) when cond is false. The fallback uses a fixed name: repeated
    identical extern declarations in one translation unit are compatible, so no

Platform/FreeRtos/Source/SolidSyslogFreeRtosMutex.c

@@ -26,12 +26,12 @@ static inline SemaphoreHandle_t FreeRtosMutex_AsHandle(struct SolidSyslogFreeRto
 void FreeRtosMutex_Initialise(struct SolidSyslogMutex* base)
 {
     struct SolidSyslogFreeRtosMutex* self = FreeRtosMutex_SelfFromBase(base);
-    /* xSemaphoreCreateMutexStatic returns NULL only when
-     * configSUPPORT_STATIC_ALLOCATION is not 1 — a compile-time config
-     * gate, not a runtime failure mode. Guarded anyway so a misconfigured
-     * integrator falls back to the NullMutex vtable instead of corrupting
-     * Lock/Unlock with a dangling handle, mirroring PosixMutex's defence
-     * against pthread_mutex_init failure. */
+    /* The storage is ours, so this cannot fail for want of memory; the kernel
+     * returns NULL only when handed a NULL buffer, which this call never does.
+     * configSUPPORT_STATIC_ALLOCATION is a compile-time requirement rather than
+     * a runtime one — without it the function does not exist to call. The
+     * branch is therefore defensive: an unexpected NULL leaves the NullMutex
+     * vtable in place rather than a dangling handle in Lock/Unlock. */
     if (xSemaphoreCreateMutexStatic(&self->Buffer) != NULL)
     {
         self->Base.Lock = FreeRtosMutex_Lock;

Platform/FreeRtos/Source/SolidSyslogFreeRtosMutexPrivate.h

@@ -13,8 +13,8 @@
 
 /* xSemaphoreCreateMutexStatic returns a handle that is the same pointer
  * as the StaticSemaphore_t passed in, so the per-instance struct doesn't
- * carry a separate SemaphoreHandle_t — the kernel-primitive layout matches
- * the Posix (pthread_mutex_t) and Windows (CRITICAL_SECTION) adapters. */
+ * carry a separate SemaphoreHandle_t — the primitive is embedded directly,
+ * as in every Mutex adapter. */
 struct SolidSyslogFreeRtosMutex
 {
     struct SolidSyslogMutex Base;

Platform/LwipRaw/Interface/SolidSyslogLwipRawDnsResolver.h

@@ -18,7 +18,7 @@
  *  - Any other immediate rejection, or the deadline elapsing, fails the Resolve
  *    so the caller's unresolved-host error path runs.
  *
- *  The transport is ignored. Requires LWIP_DNS=1. See docs/integrating-lwip.md. */
+ *  The transport is ignored. Requires LWIP_DNS=1. See docs/platforms/lwipraw/setup.md. */
 #ifndef SOLIDSYSLOGLWIPRAWDNSRESOLVER_H
 #define SOLIDSYSLOGLWIPRAWDNSRESOLVER_H
 

Platform/LwipRaw/Interface/SolidSyslogLwipRawMarshal.h

@@ -10,13 +10,15 @@
  *  - NO_SYS=1 (bare metal, no RTOS): the default direct-call marshal is correct
  *    — one execution context, no core to protect.
  *  - NO_SYS=0 (RTOS with a tcpip thread): the integrator installs a marshal that
- *    hops onto that thread — e.g. tcpip_callback_with_block, or a
- *    LOCK_TCPIP_CORE / UNLOCK_TCPIP_CORE pair.
+ *    hops onto that thread — a LOCK_TCPIP_CORE / UNLOCK_TCPIP_CORE pair, or a
+ *    mailbox post that waits for the callback to run.
  *
  *  The marshal MUST invoke its callback synchronously, before it returns: the
  *  wrapper reads results the callback writes immediately after the hop, so an
- *  asynchronous marshal is caller error. tcpip_callback_with_block(.., block=1)
- *  honours this; a bare tcpip_callback(..) does not. See docs/integrating-lwip.md. */
+ *  asynchronous marshal is caller error. Core locking satisfies this directly.
+ *  A mailbox post does not on its own — tcpip_callback_with_block(.., block=1)
+ *  blocks until the message is accepted, not until it is executed — so such a
+ *  marshal must wait for completion itself. See docs/platforms/lwipraw/setup.md. */
 #ifndef SOLIDSYSLOGLWIPRAWMARSHAL_H
 #define SOLIDSYSLOGLWIPRAWMARSHAL_H
 

Platform/LwipRaw/Interface/SolidSyslogLwipRawTcpStream.h

@@ -1,6 +1,6 @@
 /** @file
  *  A TCP stream over the lwIP Raw API, for a StreamSender or as the byte
- *  transport under a TlsStream.
+ *  transport under a TLS stream.
  *
  *  Every lwIP call runs under the SolidSyslogLwipRaw_Marshal hop; the callbacks
  *  lwIP fires back (connected / recv / err) only flip flags, so they stay
@@ -28,7 +28,7 @@
  *  callback nulls the pcb pointer, and Close only calls tcp_close when the
  *  pointer is still live, so a released pcb is never closed twice. Accepted
  *  pbufs are always freed on close regardless of pcb state. See
- *  docs/integrating-lwip.md for the full integrator guide. */
+ *  docs/platforms/lwipraw/setup.md for the full integrator guide. */
 #ifndef SOLIDSYSLOGLWIPRAWTCPSTREAM_H
 #define SOLIDSYSLOGLWIPRAWTCPSTREAM_H
 

Platform/LwipRaw/Source/SolidSyslogLwipRawTcpStream.c

@@ -339,7 +339,7 @@ static bool LwipRawTcpStream_OutputResultIsAcceptable(err_t outputErr)
 static SolidSyslogSsize LwipRawTcpStream_Read(struct SolidSyslogStream* base, void* buffer, size_t size)
 {
     /* SolidSyslogStream_Read returns < 0 to signal EOF/error (socket closed
-     * internally); -1 is the in-tree convention shared with Posix/Winsock/PlusTcp. */
+     * internally); -1 is the in-tree convention across the Stream adapters. */
     static const SolidSyslogSsize READ_FAILED = -1;
 
     struct SolidSyslogLwipRawTcpStream* self = LwipRawTcpStream_SelfFromBase(base);

Platform/MbedTls/Interface/SolidSyslogMbedTlsAesGcmPolicy.h

@@ -33,7 +33,7 @@ SOLIDSYSLOG_EXTERN_C_BEGIN
         void* KeyContext; /**< Passed back to GetKey unchanged; NULL is fine. */
         struct mbedtls_ctr_drbg_context* Rng; /**< Seeded CTR-DRBG each record's 12-byte nonce is drawn from;
                                             required and caller-owned. Injected because mbedTLS has no
-                                            context-free RNG, unlike the OpenSSL sibling's RAND_bytes. */
+                                            context-free RNG. */
     };
 
     /** Draw an AES-GCM policy from the pool. Bad config (NULL GetKey or NULL Rng)

Platform/MbedTls/Interface/SolidSyslogMbedTlsStream.h

@@ -1,8 +1,8 @@
 /** @file
  *  TLS over an injected byte-transport Stream via Mbed TLS, itself a Stream — so
  *  a StreamSender speaks TLS to a remote collector without knowing the transport
- *  underneath (PosixTcpStream, PlusTcpTcpStream, or any caller-supplied byte
- *  Stream).
+ *  underneath, whether a TCP stream from a platform pack or one the caller
+ *  supplies.
  *
  *  What the stream does through its vtable is the substance:
  *
@@ -27,7 +27,7 @@
  *  ssl_config / ssl_context state and never calls process-global mbedTLS APIs
  *  (platform setup/teardown, psa_crypto_init, threading-alt, debug hooks), so it
  *  drops into an integrator process that already uses Mbed TLS elsewhere. See
- *  docs/integrating-mbedtls.md. */
+ *  docs/platforms/mbedtls/setup.md. */
 #ifndef SOLIDSYSLOGMBEDTLSSTREAM_H
 #define SOLIDSYSLOGMBEDTLSSTREAM_H
 

Platform/MbedTls/Source/SolidSyslogMbedTlsAesGcmPolicy.c

@@ -149,7 +149,7 @@ static bool MbedTlsAesGcmPolicy_FetchKey(struct SolidSyslogMbedTlsAesGcmPolicy*
  * adjacent as same-typed scalar parameters; the trailer/header layout lives in
  * one place. The nonce is expected already in Trailer[0..GCM_NONCE_SIZE). One-
  * shot AEAD — mbedTLS computes the whole tag in a single call (output == input
- * is permitted for GCM encryption), unlike OpenSSL's incremental EVP chain. */
+ * is permitted for GCM encryption). */
 static bool MbedTlsAesGcmPolicy_GcmEncrypt(const struct SolidSyslogSecurityRecord* record, const uint8_t* key)
 {
     uint8_t* body = &record->Content[record->HeaderLength];