Joseph Doherty
9e57bfd451
**F41 — public-api baselines (M6 DoD bullet 5)**
`design/public-api/{crate}.txt` for all 9 workspace crates, generated
via `cargo +nightly public-api --simplified -p <crate>`. Per-crate
baseline sizes:
- mxaccess-codec: 2516 lines
- mxaccess-asb: 1258 lines
- mxaccess-rpc: 1273 lines
- mxaccess-asb-nettcp: 708 lines
- mxaccess: 542 lines
- mxaccess-galaxy: 374 lines
- mxaccess-callback: 170 lines
- mxaccess-compat: 123 lines
- mxaccess-nmx: 118 lines
`design/public-api/README.md` documents the update procedure
(install nightly + cargo-public-api, regenerate the affected baseline
on intentional API changes, commit alongside).
`.github/workflows/rust.yml` gains a `public-api` job that runs the
same diff against the committed baseline; drift fails CI with a
unified diff in the log so the PR author can either revert or
update the baseline.
**F44 reconciliation — multi-record DataUpdate codec**
Cherry-picked from the F44 sub-agent's worktree (commit `aec6a0c`):
`subscription_message.rs::parse_data_update` now loops over
`record_count` like `parse_subscription_status` does, accepting any
positive count. The .NET reference still hard-throws on
`record_count != 1`; the Rust codec deliberately diverges per the F44
evidence walk against `captures/094-frida-buffered-separate-writer/
frida-events.tsv:145` (a `0x33` DataUpdate body with `record_count = 2`,
inner_length = 23 (preamble) + 2 * 19 (records) = 61, post a
separate-session writer triggering two value changes inside one
`SetBufferedUpdateInterval(1000)` window).
Two new round-trip tests:
- `data_update_multi_record_round_trip` — synthesises a 2-record body,
parses, asserts both records decode to expected Int32 values.
- `data_update_capture_094_truncated_record_errors` — truncates the
capture-094 fixture mid-second-record, asserts CodecError::Decode.
New wire-byte fixtures under `crates/mxaccess-codec/tests/fixtures/m6-buffered/`:
- `094-line145-dataupdate-recordcount2.bin` (57 bytes, `0x33` multi-record)
- `094-line48-substatus-recordcount2.bin` (101 bytes, `0x32` multi-record)
R2 in `design/70-risks-and-open-questions.md` updated from
"single-sample (settled silently)" to "settled per option (a) — codec
relaxed; multi-record observed in production-stack tracing."
`design/followups.md`: F44's verdict updated to reflect the
contradiction-then-relaxation, with reference to the new tests +
fixtures.
Workspace 792 → 794 tests pass; clippy clean; rustdoc clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
64 lines
2.2 KiB
Markdown
64 lines
2.2 KiB
Markdown
# `cargo public-api` baselines
|
|
|
|
F41 — public-api baseline established 2026-05-06. One file per
|
|
workspace crate; each is the verbatim output of
|
|
`cargo +nightly public-api --simplified -p <crate>`.
|
|
|
|
## Why a baseline
|
|
|
|
`mxaccess` and friends are heading for `cargo publish`. Once the
|
|
crates are on crates.io, semver-breaking changes to the public surface
|
|
need to be intentional. The baseline is what CI diffs against to
|
|
catch unintentional drift.
|
|
|
|
## Update procedure
|
|
|
|
When a PR intentionally changes the public API:
|
|
|
|
1. Build the crate against nightly + `cargo-public-api`:
|
|
```powershell
|
|
rustup toolchain install nightly # one-time
|
|
cargo install cargo-public-api # one-time
|
|
```
|
|
2. Regenerate the affected baseline file:
|
|
```powershell
|
|
cd rust
|
|
cargo +nightly public-api --simplified -p <crate> > ../design/public-api/<crate>.txt
|
|
```
|
|
3. Commit the regenerated file alongside the API change. Reviewers
|
|
inspect the diff at `design/public-api/<crate>.txt` to verify the
|
|
intent matches the wire-up.
|
|
|
|
## CI
|
|
|
|
`.github/workflows/rust.yml` runs `cargo +nightly public-api --simplified -p <crate>`
|
|
for each workspace crate after the standard build/test/clippy/fmt
|
|
matrix and `diff`s the live output against the committed baseline.
|
|
Drift fails the CI step; the PR author either adjusts the
|
|
implementation or updates the baseline (per the procedure above).
|
|
|
|
## What `--simplified` strips
|
|
|
|
`--simplified` (single `-s`) omits blanket impls (e.g.
|
|
`impl<T: Clone> Clone for Vec<T>`-style noise) but keeps everything
|
|
that's reachable through the crate's named public items. Doubling
|
|
(`-ss`) would also strip auto-trait impls (`Send`, `Sync`,
|
|
`UnwindSafe`); we don't because intentional `Send` / `Sync` losses
|
|
on a `Session` clone *are* a semver break we want to catch.
|
|
|
|
## Per-crate sizes (line counts)
|
|
|
|
Captured at baseline date:
|
|
|
|
| crate | lines |
|
|
|----------------------|------:|
|
|
| `mxaccess-codec` | ~2516 |
|
|
| `mxaccess-asb` | ~1258 |
|
|
| `mxaccess-rpc` | ~1273 |
|
|
| `mxaccess-asb-nettcp`| ~708 |
|
|
| `mxaccess` | ~542 |
|
|
| `mxaccess-galaxy` | ~374 |
|
|
| `mxaccess-callback` | ~170 |
|
|
| `mxaccess-compat` | ~123 |
|
|
| `mxaccess-nmx` | ~118 |
|