wire-codec 1.0.0

# v1.0.0 - Stable API

`wire-codec` reaches 1.0. The public surface is now frozen: every type, trait,
function signature, and observable behaviour will remain stable across the
entire 1.x line. Bug fixes, performance work, and additive features will
continue; breaking changes will not.

This release ships no new functionality on top of `0.9.0`. The work in this
release is the polish that justifies the major version: a substantive
README rewrite, a cookbook in the API reference, a fuller crate-level
rustdoc block, and the final benchmark capture.

## What 1.0 means

- **API freeze.** All public items in `wire_codec`, `wire_codec::error`,
  `wire_codec::buf`, `wire_codec::traits`, `wire_codec::varint`,
  `wire_codec::zigzag`, `wire_codec::bitfield`, and `wire_codec::framing`
  are locked. Their signatures will not change without a `2.0` release.
- **Behaviour freeze.** Encode and decode results, frame boundaries,
  error variants on existing inputs, and bit ordering are locked.
- **Wire compatibility.** A buffer produced by 1.0 will be decoded
  identically by any 1.x version. A buffer produced by any 1.x version
  will be decoded identically by 1.0.

What can still change in 1.x without a major release:

- New `Error` variants ([`Error`] is `#[non_exhaustive]`).
- New `LengthWidth` variants ([`LengthWidth`] is `#[non_exhaustive]`).
- New methods on existing types.
- New helper functions, modules, traits, or framing strategies that do
  not conflict with the existing API.
- Performance improvements that do not alter observable output.
- New feature flags. Existing feature flags remain additive.

## Documentation polish

- **README** rewritten end-to-end. Adds a "Why wire-codec?" section
  explaining the design boundaries, a feature list with cross-links into
  the API, four usage patterns (length-prefixed, delimited, varint +
  zigzag, bit-packed records), a performance table, a stability
  statement, a `no_std` and feature-flag table, and a project-layout
  diagram. The edition claim and version pin are corrected to match
  reality.
- **`docs/API.md`** gains a 1.0 stability note in the introduction and a
  new "Cookbook" section with four recipes: append-only stream over a
  growing buffer, fixed-output buffer with `BufferFull` back-pressure,
  length-prefixed envelope around a structured record, and the
  pre-sized-output hot-loop pattern.
- **Crate-level rustdoc** in `src/lib.rs` rewritten with a "When to
  reach for this crate" section, a module map table, a stability
  section that mirrors the README, and a feature-flag table. Doctest in
  the rustdoc block continues to pass.

## Benchmark baseline at 1.0

Captured on the development machine (Windows 11, single thread, release
profile). Numbers will vary by hardware; these are the reference for
regression detection.

### `benches/codec.rs`

| Operation                                   | ns/op   |
| ------------------------------------------- | ------- |
| `varint::encode_u32` (value 300)            | 0.36    |
| `varint::encode_u32` (`u32::MAX`)           | 0.72    |
| `varint::decode_u32` (2 bytes)              | 0.18    |
| `varint::decode_u32` (5 bytes)              | 0.18    |
| `varint::encode_u64` (`u64::MAX`)           | 1.08    |
| `varint::decode_u64` (10 bytes)             | 1.82    |
| `zigzag::encode_i32` (-1)                   | 0.41    |
| `zigzag::encode_i64` (`i64::MIN`)           | 0.21    |
| `ReadBuf::read_u32_be`                      | 1.44    |
| `WriteBuf::write_u32_be`                    | 1.53    |

### `benches/framing.rs`

| Operation                                       | ns/op   |
| ----------------------------------------------- | ------- |
| `LengthPrefixed::write_frame` (64 B)            | 1.62    |
| `LengthPrefixed::next_frame` (64 B)             | 1.60    |
| `Delimited::next_frame` (short line)            | 2.02    |
| `Delimited::next_frame` (1 KiB scan + CRLF)     | 1324    |

The linear byte-by-byte scan inside `Delimited::next_frame` remains the
obvious candidate for future SIMD acceleration in a 1.x release.

## What did not change from 0.9.0

- No new types. No new traits. No new functions.
- No behavioural changes. Every test that passed against 0.9.0 passes
  unchanged against 1.0.0.
- No new dependencies. The crate still has zero runtime dependencies and
  one dev-only dependency (`proptest`, capped at `<1.6` for MSRV 1.75).
- No CI changes. The build matrix and supply-chain checks introduced in
  0.9.0 carry forward unchanged.

## Verification

Built and tested green across the full directives matrix:

- `cargo build` (default features)
- `cargo build --no-default-features`
- `cargo build --all-features`
- `cargo +1.75 build --all-features --tests`
- `cargo +1.75 test --all-features`
- `cargo fmt --all -- --check`
- `cargo clippy --all-targets --all-features -- -D warnings`
- `cargo +1.75 clippy --all-targets --all-features -- -D warnings`
- `RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features`
- `cargo bench --bench codec`
- `cargo bench --bench framing`

Test totals: 26 unit + 5 integration + 6 + 5 + 6 + 3 property + 3 smoke +
18 doctests = **72 tests** green on both stable and MSRV 1.75.

## Compatibility

- Edition: `2021`
- MSRV: Rust `1.75`
- License: Apache-2.0 OR MIT
- Platforms: Linux, macOS, Windows (CI on all three, stable + 1.75)
- Runtime dependencies: none
- Dev dependencies: `proptest` (test-only)

## Migration from 0.9.0

None required. `1.0.0` is `0.9.0` plus documentation. A `cargo update -p
wire-codec` is sufficient.

If you are migrating from `0.5.0` directly to `1.0.0`, the only API
change is `framing::Delimited::new` now returns
`Result<Delimited<'_>, Error>`. See the 0.9.0 release note for the
migration recipe.

## Acknowledgements

`wire-codec` is published under the dual Apache-2.0 OR MIT license and is
open to contributions under the same terms. The supply chain is enforced
by `cargo audit` and `cargo deny` in CI; the standards it adheres to are
captured in [`REPS.md`](../../REPS.md).