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:
+21
-27
@@ -1,9 +1,7 @@
|
||||
# Proof of feature-completeness
|
||||
# Proofs
|
||||
|
||||
"Feature-complete" is a claim that the code must prove, not the
|
||||
README. These eight commands are the proof. If they all exit zero
|
||||
on a fresh clone, the codebase implements what
|
||||
[COMPLIANCE.md](COMPLIANCE.md) claims.
|
||||
Eight commands. If they all exit zero on a fresh clone, the codebase
|
||||
implements what [COMPLIANCE.md](COMPLIANCE.md) claims.
|
||||
|
||||
| # | Command | What it proves |
|
||||
|---|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
|
||||
@@ -16,11 +14,9 @@ on a fresh clone, the codebase implements what
|
||||
| 7 | `bash interop/secs4j_validate.sh` | **55 cross-validation checks** PASS against [secs4java8](https://github.com/kenta-shimizu/secs4java8) (independent Java implementation), covering S1/S2/S3/S5/S6/S7/S10/S14/S16, the full E40 PJ body, dynamic event reports + unsolicited S6F11 / S5F1 observation, alarm management, spool, PP management, terminal services, limits, trace, E39, and the GEM 300 streams secsgem-py couldn't easily drive |
|
||||
| 8 | `cmake -B build-fuzz -DSECSGEM_FUZZ=ON && build-fuzz/fuzz_secs2_decode -max_total_time=60` | **200 000+ random inputs** through `secs2::decode`, **1.4 M+** through `try_parse_sml` per 60 s lane, ASan + UBSan + libFuzzer coverage, **0 crashes** |
|
||||
|
||||
Plus, on every push to `main`, [Gitea Actions](.gitea/workflows/ci.yml)
|
||||
runs both a **Release build + full test suite** and a separate
|
||||
**ThreadSanitizer lane** that builds with `-fsanitize=thread` and
|
||||
fails on any race. All 445 cases / 2 753 assertions pass under TSan
|
||||
clean.
|
||||
CI ([Gitea Actions](.gitea/workflows/ci.yml)) runs a Release build +
|
||||
full suite and a separate `-fsanitize=thread` lane on every push to
|
||||
`main`. All 445 cases / 2 753 assertions pass under TSan clean.
|
||||
|
||||
## Per-standard test coverage
|
||||
|
||||
@@ -47,26 +43,24 @@ Every claimed standard has dedicated tests. Counts are
|
||||
| Persistence + cross-cutting | `test_job_persistence`, `test_persistence_upgrade`, `test_wire_ceid_emission`, `test_gem300_scenario`, `test_live_gem300`, `test_thread_safety`, `test_metrics_prometheus`, `test_robustness_fuzz` | 32 |
|
||||
| **Total** | | **445** |
|
||||
|
||||
A single command to see this live: `docker compose run --rm builder
|
||||
/app/build/secsgem_tests --list-test-cases | wc -l` (currently 445).
|
||||
`docker compose run --rm builder /app/build/secsgem_tests --list-test-cases | wc -l`
|
||||
currently reports 445.
|
||||
|
||||
## What each proof actually demonstrates
|
||||
## Categories of evidence
|
||||
|
||||
The eight commands above split into four kinds of evidence:
|
||||
The eight commands split into four kinds:
|
||||
|
||||
- **Internal** (#1, #2, #4, #5) — our code testing our code: unit
|
||||
suite, conformance harness, soak property test, config validator.
|
||||
Necessary but not independent.
|
||||
- **External, second implementation** (#3, #7) — round-trip against
|
||||
secsgem-py 0.3.0 (Python) and secs4java8 (Java). Two independent
|
||||
SECS implementations must agree with us on every frame.
|
||||
- **Internal** (#1, #2, #4, #5) — unit suite, conformance harness,
|
||||
soak property test, config validator. Necessary but not
|
||||
independent.
|
||||
- **External, second implementation** (#3, #7) — secsgem-py (Python)
|
||||
and secs4java8 (Java). Two independent SECS implementations agree
|
||||
on every frame.
|
||||
- **External, third codec** (#6) — Wireshark's HSMS dissector,
|
||||
written by network-protocol authors who don't share code with
|
||||
either of us. Catches framing bugs the implementations might both
|
||||
share.
|
||||
written by network-protocol authors with no shared code. Catches
|
||||
framing bugs the implementations might share.
|
||||
- **External, structural search** (#8) — libFuzzer + ASan + UBSan
|
||||
exploring the decoder and SML parser surface for crashes, memory
|
||||
errors, and UB.
|
||||
over the decoder and SML parser surface.
|
||||
|
||||
See [VERIFICATION.md](VERIFICATION.md) for the full test plan and
|
||||
the rationale for each external validator.
|
||||
[VERIFICATION.md](VERIFICATION.md) covers each external validator in
|
||||
detail.
|
||||
|
||||
Reference in New Issue
Block a user