docs(api): per-crate public API audit for 1.0 (#42)

[joaquinbejar]

Closes #42.

Summary

The 1.0 commitment per ADR-0007 is "the public API does not change without a major bump." This audit pass freezes the public surface across the four crates promoted to 1.0 and codifies the policy.

`#[non_exhaustive]` discipline

Added to error / event enums missing it:

• `itch_protocol::primitives::TimestampError`
• `itch_soup::LoginRejectReason`

Already present and left intact across every other error / event enum (12 total — see `API.md`).

Deliberately not applied to closed-set ITCH 5.0 enums (`Message`, `EventCode`, `Side`, …) and `SoupPacket` / `CaptureFormat`. Exhaustive `match` is intentional: a new ITCH revision lands as a separate module; a new SoupBinTCP version ditto. The codec must catch every new variant at compile time.

New tracked artifact: `API.md`

Repo-root manifest with the `#[non_exhaustive]` policy, per-crate headline shapes, the SemVer commitment in effect from 1.0, and the reproduction recipe via `cargo public-api` + `cargo semver-checks`.

Makefile gates for 1.0 release-readiness

• `make public-api` — full public surface for every promoted crate.
• `make semver-check` — `cargo semver-checks check-release` per crate.
• `make check-msrv` — build + test every promoted crate against the pinned MSRV (MSRV policy + deprecation-window discipline for 1.0 #43).
• `make pre-publish` — composes `pre-push` + the three above. The 1.0 release gate.

`cargo public-api` and `cargo semver-checks` are opt-install; the targets fail clearly if the tool is missing.

Other changes

• `itch-client::run_soup` updated with a fallback arm on `LoginRejectReason` (`#[non_exhaustive]` requires it).
• CHANGELOGs updated for `itch-protocol` and `itch-soup`.

Test plan

• `cargo build --workspace --all-features`.
• `cargo clippy --workspace --all-targets --all-features -- -D warnings`.
• `cargo test --workspace --all-features`.
• `cargo fmt --all --check`.
• `RUSTDOCFLAGS=-D warnings cargo doc --workspace --no-deps`.

[Copilot]

Pull request overview

This PR codifies the workspace’s pre-1.0 public API audit and forward-compatibility policy (notably via #[non_exhaustive] discipline), and adds local release-readiness gates to help prevent accidental SemVer breaks as the promoted crates approach 1.0.

Changes:

• Add #[non_exhaustive] to itch_soup::LoginRejectReason and itch_protocol::primitives::TimestampError, plus update itch-client to handle forward-compatible matching.
• Introduce API.md as a tracked workspace-level API/policy artifact, and update per-crate changelogs to record the audit decisions.
• Add Makefile “1.0 release gates” targets (public-api, semver-check, check-msrv, pre-publish) for repeatable pre-release validation.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
Makefile	Adds new release-readiness targets for API surface, SemVer checks, and MSRV checks (but check-msrv parsing is currently broken).
crates/itch-soup/src/lib.rs	Marks LoginRejectReason as #[non_exhaustive] and documents the forward-compat rationale.
crates/itch-soup/CHANGELOG.md	Records the #[non_exhaustive] change and downstream fallback update for 1.0 audit.
crates/itch-protocol/src/primitives.rs	Marks TimestampError as #[non_exhaustive] with rationale.
crates/itch-protocol/CHANGELOG.md	Records the TimestampError #[non_exhaustive] policy decision for the audit.
crates/itch-client/src/main.rs	Adds a fallback match arm to handle LoginRejectReason becoming #[non_exhaustive].
Cargo.lock	Updates lockfile (removes async-trait from itch-source-kafka dependencies).
API.md	Adds workspace-level API audit/policy document and reproduction instructions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.