docs(design): describe what shipped

[michen00]

What changes, and why

Five statements in docs/rust-port-design.md that do not match the tree. Three describe a plan the implementation improved on rather than a mistake, which is worth saying because the document is a design record and the improvement is the interesting part.

The error type (:232). "A small error enum implementing Display and From by hand." No such impl exists:

$ grep -rn 'impl.*Display\|impl.*From<\|impl.*Error for' src/*.rs src/bin/*.rs
  (no matches)

ReadError derives Debug, Clone, Copy, PartialEq, Eq and nothing more, and every path renders it through one describe(path, error) -> &'static str into the fixed vocabulary the section above defines. That is better than the plan — the vocabulary belongs to the tool rather than to the type, and a Display impl would have invited a second way to render it — so the paragraph now says so.

The message shapes (:186). "The two messages carrying it" — there are three. The --ignore-file read carries the same vocabulary, in both implementations (unwrap.py:1089, src/cli.rs:565), and has since before the paragraph naming the other two.

The lint job (:236). There is none, and no revision of the workflow has had one. CI.yml's job ids are pre-commit test coverage hook action mirror-identity rust-lint rust-test rust-test-stable parity build — the linting job is pre-commit, so a reader checking the list finds four of five and one dangling id.

The parity bullet (:240). It omits that job's first and primary step — the CLI tier over both binaries, on all three platforms — and says "one fresh seed per run" where the job takes a range:

--start 1 --count 400
--start $(( github.run_number * 400 + 100000 )) --count 200

The mirror argument (:90). Still hung on "a generated force-push". The push appends a signed commit through createCommitOnBranch and has no force path, which mirrors.yml and scripts/push_mirror.py both state at length. The argument survives the correction unaltered — an irreversible act behind a generated commit is the objection — so only the mechanism's name changes.

Corpus

The corpus is the specification, and both implementations answer to it. Tick what applies.

• This changes no behavior the corpus specifies.
• This changes what gets joined, and a case in corpus/ pins the new behavior. The case was written first and failed first.
• The change makes the tool join more than it did. The section above says what it will not eat.

Checks

• make check passes, or make test does and this touches no Rust.

make tidy, plus unwrap-markdown-prose-py --fail-on-change docs/rust-port-design.md. One Markdown file.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can add REVIEW.md to your repo root and Qodo follows it on every PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

PR Summary by Qodo

Align Rust port design record with shipped implementation

📝 Documentation 🕐 10-20 Minutes

AI Description

• Reconciles Rust error-handling design with the shipped centralized description mapping.
• Documents all read-error message shapes and actual CI parity coverage.
• Corrects mirror generation terminology from force-push to generated commit.

Diagram

graph TD
  D["Design record"] -->|documents| E["Error model"] -->|renders through| C["CLI messages"]
  D -->|matches| W["CI workflow"] -->|details| P["Parity checks"]
  D -->|corrects| M["Mirror commits"]

Loading

High-Level Assessment

Correcting stale statements in place while preserving explanations of where implementation improved on the original plan is the best fit for a design record. Keeping the inaccurate plan unchanged or moving shipped behavior elsewhere would make the document harder to verify against the repository.

Files changed (1) +5 / -5

Documentation (1) +5 / -5

rust-port-design.mdReconcile design claims with shipped Rust port behavior +5/-5

Reconcile design claims with shipped Rust port behavior

• Corrects the mirror mechanism, read-error message count, error-type design, CI job name, and parity workflow description. The revised text records where the implementation improved on the original plan without changing behavior.

docs/rust-port-design.md

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.37%. Comparing base (1e9ac89) to head (06cf0a0).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #40   +/-   ##
=======================================
  Coverage   87.37%   87.37%           
=======================================
  Files           3        3           
  Lines         689      689           
=======================================
  Hits          602      602           
  Misses         87       87           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

🟢 Approval recommended

The changes are documentation-only and the updated statements are consistent with the current code and workflows.

Pull request overview

Updates the Rust port design record (docs/rust-port-design.md) so its CI, error-handling, and mirror-generation descriptions match the current repository implementation and workflows.

Changes:

• Corrects the mirror mechanism wording from “generated force-push” to “generated commit” (consistent with createCommitOnBranch/no-force-path behavior).
• Updates error-handling documentation to reflect the ReadError + describe(...) -> &'static str fixed-vocabulary approach (no Display/From impls).
• Fixes CI job references and parity description (pre-commit job name; parity runs CLI tier on 3 OSes plus fuzzing over fixed + run-derived seed ranges).

File summaries

File	Description
docs/rust-port-design.md	Aligns the design documentation with shipped behavior for mirrors, error rendering, CI job naming, and parity/fuzzing scope.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.