docs: streamline tone across reference docs
tests / build-and-test (push) Successful in 2m7s
tests / thread-sanitizer (push) Successful in 2m35s
tests / tshark-dissector (push) Successful in 2m19s
tests / secs4j-interop (push) Successful in 36s
tests / libfuzzer (push) Successful in 3m8s

Tone pass across the non-tutorial markdown — README, PROOFS,
ARCHITECTURE, BENCHMARKS, COMPLIANCE, FAQ, MES_INTEROP, SECURITY,
and interop/README.  Three patterns came out:

- Bug-history war stories ("Past interop sweeps surfaced…",
  "What these harnesses caught: 1. Strict U-width parsing…").
- Chat-with-reader framing ("Don't skip TLS unless…", "Treat as a
  punch list", "If you're running in a pod…", "Misconfiguration
  incidents drop dramatically").
- Self-referential narration ("we ship", "our codec", "the
  codebase's most-tested layer", "three orders of magnitude above
  fab load", "the gift that keeps giving").

README also drops the standalone ThreadSanitizer subsection under
Build details (now a single line under the new Testing section).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
2026-06-10 00:00:06 +02:00
parent d63c92166d
commit dae6bfd747
9 changed files with 130 additions and 219 deletions
+18 -25
View File
@@ -93,10 +93,8 @@ about format codes but lenient about U-widths in identifier fields
(per `messages_helpers::any_unsigned_first`) — that's how secsgem-py
interop works without breaking spec-correctness.
The codec is the most-tested layer in the codebase: 196 SEMI E5 KAT
assertions, 120+ unit tests, plus libFuzzer with 70 000+ random
inputs per minute. Touch it carefully; it's the foundation
everything else stands on.
Coverage on the codec: 196 SEMI E5 KAT assertions, 120+ unit tests,
libFuzzer with 70 000+ random inputs per minute under ASan + UBSan.
## 4. Transport (`hsms/`, `secsi/`)
@@ -407,9 +405,9 @@ example to mirror.
### 9.5. New transport
`hsms::Connection` and `secsi::Protocol` are the two we ship. A
third (e.g. HSMS-over-TLS as a first-class thing, or HSMS over a
sidecar IPC) follows the same contract:
`hsms::Connection` and `secsi::Protocol` are the two shipped
transports. A third (e.g. HSMS-over-TLS as a first-class thing, or
HSMS over a sidecar IPC) follows the same contract:
1. Accept a transport socket / endpoint.
2. Expose `set_message_handler(...)`, `send_request(...)`,
@@ -438,11 +436,10 @@ by:
- The ThreadSanitizer CI lane — every test under
`-fsanitize=thread`
If you're adding work that lives on another thread (sensor poll
loop, separate metrics scraper, signal handler), marshal back to
the io_context with `asio::post(io.get_executor(), ...)`. Don't
add locks; they'll diverge from the contract and the next
contributor will be confused.
Work that lives on another thread (sensor poll loop, separate
metrics scraper, signal handler) must marshal back to the
io_context via `asio::post(io.get_executor(), ...)`. The model
contract has no locks; adding any would diverge from it.
---
@@ -480,23 +477,19 @@ contributor will be confused.
---
## 13. What we deliberately don't do
## 13. Deliberate non-features
- **No DI framework, no service locator.** Stores are owned by the
model; the model is owned by your application; everything else is
passed in by reference. C++20 has no language-level DI, and adding
one to a codebase this size is overhead with no payoff.
model; the model is owned by the application; everything else
passes by reference.
- **No singleton state.** The model is a value, not a global.
- **No std::shared_ptr-everywhere.** asio handlers extend the
lifetimes that need extending; the rest is owned by-value. Read
`Connection`'s lifetime contract in `hsms/connection.hpp` if you're
ever in doubt.
- **No exceptions across the API boundary** — the codec throws
lifetimes that need extending; the rest is owned by-value.
`Connection`'s lifetime contract is documented in
`hsms/connection.hpp`.
- **No exceptions across the API boundary.** The codec throws
`secs2::CodecError` internally, but every public accessor returns
`std::optional` or returns a bool. Exceptions are reserved for
`std::optional` or a bool. Exceptions are reserved for
programmer-error / corrupt-input paths.
Every one of those constraints came from real review pressure on
prior iterations. Pushing back on them is welcome but please read
the existing tests first; the codebase's architecture is what makes
the property fuzz and the TSan lane feasible.
The TSan lane and the property fuzz depend on these constraints.