docs(stripe): say why async-stripe is pinned to a candidate

CHANGELOG.md

@@ -94,6 +94,15 @@ all are the kind 0.0.x exists to make.
   licence, a wildcard version or a source outside crates.io, checked on every
   push and again daily — an advisory lands against a tree that has not changed.
 
+- **`kasapay-stripe` says which `async-stripe` it is built against**, and why it
+  is pinned exactly rather than ranged. `=1.0.0-rc.8` is still the newest
+  candidate published and there is no 1.0.0; a candidate has changed generated
+  types before, so the version is chosen here rather than by resolution. The
+  cost to a caller is that a crate depending on `async-stripe` itself must be on
+  the same candidate — two exact pins at different candidates do not resolve
+  together — and `Stripe::client` exists so that reaching past what this crate
+  models needs no second dependency at all.
+
 - **`Stripe::capture`, whole or partial.** Stripe leaves `amount` at what was
   authorised and reports a partial capture in `amount_received`, so
   `Charge::amount` reads the latter where the two differ — the trait promises

Cargo.toml

@@ -28,9 +28,8 @@ tracing = "0.1.44"
 reqwest = { version = "0.13.4", default-features = false, features = ["form", "json", "query", "rustls"] }
 url = "2.5.8"
 
-# The 1.0 line is a prerelease but it is the maintained one: rc.8 is newer than
-# 0.41 and it is what the weekly OpenAPI regeneration lands on. Pinned exactly
-# because a prerelease may break between candidates.
+# The maintained line is the 1.0 prerelease, not 0.41. Pinned exactly because a
+# candidate has changed generated types under us; loosen to "1" when 1.0.0 ships.
 async-stripe = { version = "=1.0.0-rc.8", default-features = false, features = ["rustls-tls-native", "rustls-aws-lc-rs"] }
 async-stripe-core = { version = "=1.0.0-rc.8", default-features = false, features = ["payment_intent", "refund"] }
 async-stripe-shared = { version = "=1.0.0-rc.8", default-features = false }

crates/kasapay-stripe/src/lib.rs

@@ -31,6 +31,19 @@
 //! `Idempotency-Key`, so replaying a charge with the same key takes the money
 //! once. Without a key, a retry is a second charge.
 //!
+//! # Which `async-stripe`
+//!
+//! Exactly `1.0.0-rc.8`, pinned rather than ranged. The 1.0 line is a
+//! prerelease and a candidate has changed generated types before —
+//! `PaymentIntent` gained a public field between rc.6 and rc.7 — so which one
+//! this is built against is not left to resolution.
+//!
+//! It costs a caller one thing: a crate that depends on `async-stripe` itself
+//! has to be on the same candidate, because two exact pins at different
+//! candidates cannot resolve together. [`Stripe::client`] hands the client back
+//! so that reaching what this crate does not model needs no second dependency.
+//! The pin becomes a range the day 1.0.0 ships.
+//!
 //! # Example
 //!
 //! ```no_run