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:
+10
-46
@@ -1,13 +1,11 @@
|
||||
# External cross-validation harnesses
|
||||
|
||||
Every harness in this directory exists so a reviewer doesn't have to
|
||||
take our word for it. Each one validates our C++ codec / framing /
|
||||
dispatch against an **independent third-party implementation** that
|
||||
read the SEMI standards without talking to us.
|
||||
Each harness in this directory validates the C++ codec, framing, and
|
||||
dispatch against an **independent third-party implementation** of
|
||||
the same SEMI standards.
|
||||
|
||||
See [`../docs/VERIFICATION.md`](../docs/VERIFICATION.md) for the full
|
||||
test plan and the honest accounting of which proofs are external vs
|
||||
internal.
|
||||
See [`../docs/VERIFICATION.md`](../docs/VERIFICATION.md) for the
|
||||
internal-vs-external breakdown across all validators.
|
||||
|
||||
## What's here
|
||||
|
||||
@@ -83,44 +81,11 @@ Drops the host link mid-flight, kills the server, restarts it, and
|
||||
asserts the spooled S5F1 / S6F11 frames drain to the host on
|
||||
reconnect.
|
||||
|
||||
## What these harnesses caught
|
||||
|
||||
Real bugs surfaced during interop development (now fixed):
|
||||
|
||||
1. **Strict U-width parsing rejected U1-encoded identifiers.** SEMI
|
||||
E5 declares DATAID, RPTID, VID, CEID, ALID, EXID etc. as
|
||||
`U1 | U2 | U4 | U8`; secsgem-py picks the smallest width that
|
||||
fits. Our scalar accessors were strict. Now lenient with
|
||||
range-checked downcasts (`messages_helpers.hpp::any_unsigned_first`).
|
||||
|
||||
2. **PPBODY rejected when sent as ASCII.** SEMI allows PPBODY to be
|
||||
`ASCII | Binary | List`; secsgem-py defaults to ASCII. Added the
|
||||
`BINARY_OR_ASCII` codegen type and the `as_text_or_binary`
|
||||
accessor.
|
||||
|
||||
3. **Missing S1F23 / S1F24 (Collection Event Namelist).** Added the
|
||||
wire schema, the `vids_for(ceid)` accessor, and the dispatch
|
||||
handler.
|
||||
|
||||
4. **Missing S10F3 handler (host→equipment Terminal Display).** Our
|
||||
server only registered S10F1; per SEMI E5 §13 those are opposite
|
||||
directions. Added the missing dispatch.
|
||||
|
||||
5. **TSan use-after-free in `act_exception_complete`** (test code,
|
||||
not library): held a pointer across `fire_internal(RecoveryComplete)`
|
||||
which deletes the entry. Found by the ThreadSanitizer lane on
|
||||
first run.
|
||||
|
||||
The C++ test suite stayed green through every one of these fixes —
|
||||
the changes were purely permissive widenings or additive features,
|
||||
no existing behaviour broke.
|
||||
|
||||
## When to add a new validator
|
||||
|
||||
A new third-party SECS implementation, or a new dissector, or a new
|
||||
fuzzer target — anything that exercises our wire surface from an
|
||||
angle the existing five don't cover — is worth adding. The pattern
|
||||
is consistent:
|
||||
A new third-party SECS implementation, dissector, or fuzzer target
|
||||
that exercises the wire surface from an angle the existing five
|
||||
don't cover is worth adding. The pattern is consistent:
|
||||
|
||||
1. New script / harness lives here (or a sidecar Docker context for
|
||||
non-Python validators).
|
||||
@@ -129,6 +94,5 @@ is consistent:
|
||||
4. Surfaced in [`../docs/PROOFS.md`](../docs/PROOFS.md) if it adds a
|
||||
meaningful new dimension.
|
||||
|
||||
Bug reports from a new validator → file at
|
||||
`raphael@maenle.net` with the wire trace, the validator's output,
|
||||
and the equipment YAML so we can reproduce.
|
||||
Bug reports from a new validator → file at `raphael@maenle.net`
|
||||
with the wire trace, the validator's output, and the equipment YAML.
|
||||
|
||||
Reference in New Issue
Block a user