docs: streamline tone across reference docs
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:
+18
-25
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user