Joseph Doherty
fe2a6db786
rust / build / test / clippy / fmt (push) Has been cancelled
Layout:
- src/ .NET 10 x64 reference: MxNativeCodec, MxNativeClient,
MxAsbClient, probes, tests, harnesses. Executable spec.
- design/ Architectural plan for the Rust port (M0–M6), error
model, protocol invariants, risks (R1–R16), adversarial
review log (review.md).
- rust/ Rust workspace. M0 skeleton + M1 codec parity.
mxaccess-codec: 215 unit tests + 2 cross-implementation
parity tests (byte-identical against .NET reference).
Other crates are M0 stubs awaiting M2+.
- captures/ Frida + netsh + pcap evidence per CLAUDE.md
("captures are evidence, not throwaway logs").
- analysis/ Decompiled C# (frida/proxy/decompiled-*),
Ghidra exports for native DLLs (`exports/` only —
working state at `projects/` and AVEVA's input
binaries at `input/` are gitignored).
- docs/ Reverse-engineering reference docs.
- tools/ Setup-LiveProbeEnv.ps1 (Infisical credential fetcher),
Compute-Crc.ps1 (.NET parity helper).
- .github/workflows/ Rust CI: fmt + build + test + clippy on Windows.
- LICENSE MIT (Joseph Doherty, 2026).
Verified:
- cargo test --workspace → 217 passed (215 unit + 2 .NET parity), 0 failed
- cargo clippy --workspace -- -D warnings → clean
- cargo fmt --all -- --check → clean
- cargo publish --dry-run -p mxaccess-codec → packages cleanly
Excluded from history (see .gitignore):
- **/bin, **/obj, **/target — build artifacts
- analysis/ghidra/projects/ — Ghidra working state (regenerable)
- analysis/ghidra/input/ — AVEVA proprietary DLLs (vendor IP)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
32 lines
2.0 KiB
Markdown
32 lines
2.0 KiB
Markdown
# `design/` — Rust port architectural plan
|
|
|
|
This folder is the design contract for the Rust replacement of AVEVA/Wonderware MXAccess. It is the gap between the .NET reference in `src/` and the Rust crates that will be written under a sibling `rust/` workspace (per `CLAUDE.md`).
|
|
|
|
The folder is structured as a small set of focused documents. Read in order; each builds on the previous.
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `00-overview.md` | Mission, two-layer goal, architectural principles, non-goals |
|
|
| `10-raw-layer.md` | Byte-accurate raw MXAccess layer (codec + transport + session) |
|
|
| `20-async-layer.md` | Idiomatic Tokio async layer on top of the raw layer |
|
|
| `30-crate-topology.md` | Cargo workspace, crates, dependencies, build/test commands |
|
|
| `40-protocol-invariants.md` | Bill of materials: IIDs, opnums, envelope/handle bytes |
|
|
| `50-error-model.md` | `MxStatus`, error types, panic/cancellation policy |
|
|
| `60-roadmap.md` | Milestones M0..M6, validation strategy |
|
|
| `70-risks-and-open-questions.md` | Parity gaps, unproven flows, cross-platform constraints |
|
|
|
|
The design is grounded in the .NET reference at `src/` and the protocol artifacts in `docs/`, `analysis/`, and `captures/`. **Do not introduce protocol behavior in these documents that is not already proven in the reference.** When adding a new claim about wire format, cite either:
|
|
|
|
- a `.cs` file path in `src/MxNativeCodec/`, `src/MxNativeClient/`, or `src/MxAsbClient/`, or
|
|
- a `docs/*.md` spec file, or
|
|
- a `captures/0NN-frida-*` directory or `analysis/frida/*.tsv` row.
|
|
|
|
This folder is documentation, not code. When the Rust workspace is created, the design here is the contract it must satisfy. When evidence in `captures/` invalidates a design decision here, update the design first, then the code.
|
|
|
|
## Reading order
|
|
|
|
- New contributor: 00 → 30 → 10 → 40 → 20 → 50 → 60 → 70.
|
|
- Protocol question: 40 first, then the relevant section of 10.
|
|
- API question: 20 first, then 50.
|
|
- Planning a milestone: 60 first, cross-reference 70 for blockers.
|