Joseph Doherty
16f2c148e5
- design/dependencies.md: per-milestone parallelism map for M2–M6 with per-phase agent budgets (peak 4 in parallel for M5 framing wave; 7-agent maximum if M2 wave 1 + M5 framing run concurrently). - design/prompt.md: self-contained /loop driver. Step 0 triages design/followups.md (auto-resolves items whose preconditions are met, shelves the rest). Step 3 spawns parallel general-purpose agents per design/dependencies.md when the active wave has multiple lanes. Sequential lanes (M4 Session core, M5 client integration) run directly. Local-commit-only by default; explicit stop conditions; Q7 hasDetailStatus audit reminder for any new conditional-read codec port. - design/README.md: index updated to reference prompt.md, followups.md, dependencies.md, and review.md. design/followups.md is intentionally not pre-created — prompt.md Step 0 bootstraps it on first /loop run. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
38 lines
2.6 KiB
Markdown
38 lines
2.6 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 |
|
||
| `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).
|