docs: chapters 02 + 03 of the guided tour (Part 1 complete)
02 — The cast of characters: equipment, EAP, MES, fab planner, AMHS, operator. Who initiates which conversation, why the equipment is the passive side of HSMS by convention, how the AMHS handshake is out-of-band relative to SECS. Cross-references the relevant namespace and test files for each actor. 03 — Vocabulary + a wafer's journey: follows one 300 mm wafer end-to-end through a fab and labels every SECS message and acronym that fires. Introduces SVID / DVID / ECID / CEID / RPTID / ALID / PPID / MDLN / SOFTREV / HCACK / ALCD / OFLACK / CAACK / SMACK / etc. in context rather than as a list. Includes one-screen reference tables for the remaining acknowledge codes, T-timers in all four contexts (HSMS / SECS-I / E84 / E30 communication state), and a stream-by-stream summary. Part 1 (Foundations) of the guided tour is now complete — a reader who reads chapters 01–03 can describe the protocol stack, identify the actors, and recognise every acronym they'll meet in Part 2. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,72 @@
|
||||
# Proof of feature-completeness
|
||||
|
||||
"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.
|
||||
|
||||
| # | Command | What it proves |
|
||||
|---|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
|
||||
| 1 | `docker compose run --rm tests` | **445 test cases / 2 753 assertions** pass: every store, FSM, codec, parser, persistence path |
|
||||
| 2 | `docker compose run --rm builder /app/build/secs_conformance --host server --port 5000` | **47 wire-level conformance checks** PASS against a live passive equipment |
|
||||
| 3 | `docker compose run --rm interop python3 /app/interop/host_vs_cpp_server.py --host server` | **31 interop checks** PASS against secsgem-py 0.3.0 (the Python reference impl) |
|
||||
| 4 | `SECSGEM_ROBUSTNESS_SOAK=1 docker compose run --rm builder /app/build/secsgem_tests -tc='*soak*'` | **100 000 random tool operations** execute with all invariants and persistence round-trips holding |
|
||||
| 5 | `docker compose run --rm builder /app/build/secs_server --validate-config --config /app/data/equipment.yaml --state-table /app/data/control_state.yaml --pj-state-table /app/data/process_job_state.yaml --cj-state-table /app/data/control_job_state.yaml` | Every shipped YAML config passes structural + referential validation |
|
||||
| 6 | `docker compose run --rm builder bash /app/interop/tshark_validate.sh` | **69 HSMS frames** dissected by Wireshark's HSMS dissector (independent third codec) with no malformed packets |
|
||||
| 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.
|
||||
|
||||
## Per-standard test coverage
|
||||
|
||||
Every claimed standard has dedicated tests. Counts are
|
||||
`grep -c TEST_CASE`; cross-cutting tests (e.g. `test_robustness_fuzz`,
|
||||
`test_gem300_scenario`) exercise multiple standards in concert.
|
||||
|
||||
| Standard | Test files | Cases |
|
||||
|-----------------------------------|-------------------------------------------------------------------------------------------|------:|
|
||||
| **E5** — SECS-II encoding | `test_secs2`, `test_sml`, `test_messages`, `test_e5_kat`, `test_identifier_wildcards`, `test_fuzz` | 139 |
|
||||
| **E5 §13** — exceptions | `test_exceptions`, `test_exception_persistence` | 16 |
|
||||
| **E4** — SECS-I transport | `test_secsi`, `test_secsi_timers`, `test_secsi_tcp` | 27 |
|
||||
| **E37** — HSMS (SS + GS) | `test_hsms`, `test_hsms_connection`, `test_hsms_timers`, `test_hsms_s9`, `test_hsms_gs`, `test_hsms_gs_integration`, `test_s9_fallback`, `test_concurrency` | 34 |
|
||||
| **E30** — GEM core | `test_control_state`, `test_communication_state`, `test_host_handler`, `test_data_model`, `test_loader`, `test_config_validate` | 71 |
|
||||
| **E40** — process jobs | `test_process_jobs` | 21 |
|
||||
| **E94** — control jobs | `test_control_jobs` | 9 |
|
||||
| **E42** — formatted PP | `test_e42_formatted_pp` | 6 |
|
||||
| **E87** — carriers + load ports | `test_carriers`, `test_carrier_state`, `test_carrier_persistence`, `test_e87_wire_scenarios` | 27 |
|
||||
| **E90** — substrate tracking | `test_substrates`, `test_substrate_persistence` | 21 |
|
||||
| **E116** — EPT | `test_ept` | 7 |
|
||||
| **E120 / E39** — common equip / object service | `test_cem_objects` | 3 |
|
||||
| **E157** — module process tracking | `test_modules` | 5 |
|
||||
| **E84** — parallel I/O + timers | `test_e84`, `test_e84_ports`, `test_e84_timers`, `test_e84_asio_timers` | 27 |
|
||||
| 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).
|
||||
|
||||
## What each proof actually demonstrates
|
||||
|
||||
The eight commands above split into four kinds of evidence:
|
||||
|
||||
- **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.
|
||||
- **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.
|
||||
- **External, structural search** (#8) — libFuzzer + ASan + UBSan
|
||||
exploring the decoder and SML parser surface for crashes, memory
|
||||
errors, and UB.
|
||||
|
||||
See [VERIFICATION.md](VERIFICATION.md) for the full test plan and
|
||||
the rationale for each external validator.
|
||||
Reference in New Issue
Block a user