Copilot instructions for Rust

# GitHub Copilot instructions

These instructions apply to the whole Rust repository. Copilot reads them from `.github/copilot-instructions.md`.
Prefer the commands and layout below over guesses.

## Stack

This repository is a Rust crate on Cargo. Format with rustfmt, lint with cargo clippy, and use Result for recoverable failure.

## Layout

- Library code lives in `src/lib.rs` and modules under `src/`. Binaries live in `src/main.rs` or `src/bin/`.
- Integration tests live in `tests/`. Unit tests live in the module they cover.
- Keep `Cargo.toml` dependencies minimal. Do not add a crate the standard library already covers.

## Commands

- Test: `cargo test`
- Format: `cargo fmt`
- Lint: `cargo clippy --all-targets -- -D warnings`
- Build: `cargo build`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Run cargo fmt. Then run cargo clippy on non-trivial changes.
- Return `Result` for recoverable errors. `Option` is for absence, not for failure.
- Do not `unwrap` or `expect` in library paths. A binary may expect only when the failure is a programming bug.
- Do not clone your way out of the borrow checker without a one-line reason.
- Own data when the function stores it. Borrow when it only needs to look.
- Public items get a rustdoc comment when the comments setting asks for documentation.

## Testing

Add or update tests when behavior changes.

Add unit tests beside the function you changed. Cover the Ok path and one Err path.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Use the project's error type. If it has none, return `Result<T, impl std::error::Error>` only at the edge, and keep library errors typed.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not use `unsafe` to pass a lint. Unsafe needs a safety comment the project already expects.
- Do not `.clone()` in a loop to silence a lifetime.
- Do not ignore a `Result` with `let _ =`.
- Do not add `#[allow]` for a clippy lint you can fix in a few lines.

## Done when

- The requested behavior works.
- `cargo test` passes. Run `cargo clippy --all-targets -- -D warnings` when the change is more than a comment.
- The diff stays inside the task.
- You list anything you could not run.

## Review checklist

- The change matches the commands and layout in this file.
- No new dependency was added without a reason already present in the repo.
- Do not unwrap on input that an attacker can choose.
- Keep secrets out of the repo and out of tracing spans.
- Do not add unsafe to skip a validation check.