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
+17 -27
View File
@@ -9,13 +9,12 @@ equipment model), **E157** (module process tracking), **E84** (parallel
I/O), **E148** (time synchronization), **E39** (object services), plus
**E5 §13** wafer maps.
> **Status.** Every GEM Fundamental and every GEM Additional capability
> that E30 binds to a concrete SECS-II message set is implemented, and
> every GEM 300 standard the project sets out to cover is implemented
> end-to-end (state machines + stores + wire messages + dispatch). See
> §8 for what "100% GEM-compliant" can and cannot honestly mean about a
> codebase, and the README "Deferred follow-ups" section for the
> non-shipped pieces that aren't behavioural gaps.
> **Status.** Every GEM Fundamental and Additional capability that
> E30 binds to a SECS-II message set is implemented end-to-end
> (state machine + store + wire messages + dispatch), and so is
> every in-scope GEM 300 standard. §8 covers what "100%
> GEM-compliant" can and cannot mean about a codebase; the README
> "Deferred follow-ups" section lists the non-shipped pieces.
Legend:
@@ -372,10 +371,9 @@ against vendor equipment as the first-line conformance probe.
## 7. Interoperability with external implementations
Four independent external validators cross-check the codebase. None
of them shares code with us; three of them are not even C++. Full
test plan in [VERIFICATION.md](VERIFICATION.md); proof commands in
[PROOFS.md](PROOFS.md).
Four external validators cross-check the codebase. Three of them
are not C++. Full description in [VERIFICATION.md](VERIFICATION.md);
proof commands in [PROOFS.md](PROOFS.md).
**secsgem-py 0.3.0** (Python reference implementation, Apache 2.0).
Three harnesses under `interop/`:
@@ -401,10 +399,9 @@ end-to-end against a second SECS implementation.
**Wireshark / tshark HSMS dissector** (independent network-protocol
authors). `interop/tshark_validate.sh` captures a pcap of the demo
run, dissects with tshark's built-in HSMS dissector, asserts no
malformed-packet warnings and that every expected control + data
frame parses. 69 HSMS frames dissected cleanly. This catches
framing bugs that two SECS implementations might *both* share but
run, dissects with tshark's built-in HSMS dissector, and asserts no
malformed-packet warnings. 69 HSMS frames dissected cleanly per
run. Catches framing bugs two SECS implementations might share but
that a third party reading the bytes would flag.
**libFuzzer + ASan + UBSan** (coverage-guided structural search).
@@ -414,16 +411,9 @@ AddressSanitizer + UndefinedBehaviorSanitizer. 60-second CI lanes
typically explore 200 000+ inputs through `secs2::decode` and
1 400 000+ through `try_parse_sml`; 0 crashes, 0 ASan/UBSan reports.
Bugs surfaced and fixed across the four channels include: strict
per-width parsing rejected U1-encoded identifiers (SEMI E5 allows
`U1|U2|U4|U8`); PPBODY-as-ASCII was rejected; S1F23/F24 wasn't
implemented; S10F3 (host→equipment Terminal Display Single) wasn't
wired; one HSMS framing edge case caught by the tshark dissector;
several SML edge cases caught by libFuzzer.
---
## 8. What "100% GEM-compliant" honestly means here
## 8. What "100% GEM-compliant" means here
Every GEM Fundamental and every GEM Additional capability that the E30
specification defines with a concrete SECS-II message set is implemented,
@@ -450,7 +440,7 @@ What this codebase does **not** demonstrate, and what a real
GEM-compliant.
In short: this is a **GEM-conformant runtime stack with the full GEM
300 suite**, not a GEM-conformant *tool*. Pointing the runtime at a
real piece of equipment, populating the YAML files with the tool's
real SVIDs / ECIDs / alarms / capabilities / job behaviour, and wiring
the application callbacks completes the picture.
300 suite**, not a GEM-conformant *tool*. A GEM-conformant tool is
this runtime plus an application populating the YAML with real
SVIDs / ECIDs / alarms / capabilities / job behaviour and wiring the
callbacks.