# `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 |
| `dependencies.md` | Cross- and within-milestone parallelism map; agent budget per phase |
| `review.md` | Adversarial review log (BLOCKER/MAJOR/MINOR/NIT findings, all resolved) |
| `prompt.md` | `/loop` driver prompt for autonomous M2–M6 execution |
| `followups.md` | Open / resolved deferred work items; auto-triaged by `prompt.md` Step 0 (created on first /loop run if missing) |

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.
- Scheduling concurrent work: `dependencies.md` for the per-phase parallelism map.
- Driving M2–M6 autonomously via `/loop`: `prompt.md` (and the `followups.md` triage log it maintains).