Document async feature admission policy

Author: eldryoth

CHANGELOG.md

@@ -53,6 +53,8 @@
   to remain inert Cargo features.
 - Updated the v0.5 roadmap to reflect the reserved async-feature admission bar
   instead of promising Tokio wrappers before dependency review.
+- Added `docs/ASYNC.md` to define the admission requirements for any future
+  async/Tokio API while the `tokio` feature remains inert.
 - Updated security documentation for streaming wrapper buffer cleanup behavior.
 - Updated release evidence documentation for stream fuzzing and reserved SIMD
   feature-bundle checks.

README.md

@@ -255,6 +255,8 @@ Security commitments:
   boundary.
 - [docs/UNSAFE.md](docs/UNSAFE.md) inventories every current unsafe site and
   its safety invariants.
+- [docs/ASYNC.md](docs/ASYNC.md) defines the admission bar for any future
+  async/Tokio API while the `tokio` feature remains inert.
 - `runtime::backend_report()` exposes the active backend, detected candidate,
   SIMD feature status, and scalar-only security posture for audit logging.
 - `runtime::require_backend_policy()` lets deployments assert scalar execution,

docs/ASYNC.md

@@ -0,0 +1,52 @@
+# Async Admission Policy
+
+`base64-ng` does not currently provide async streaming wrappers. The `tokio`
+feature is intentionally inert and dependency-free until an async API is
+admitted through the same evidence-driven process used for SIMD and other
+security-sensitive surfaces.
+
+This keeps the published crate small and avoids adding a runtime dependency
+before the API, cancellation behavior, and security tradeoffs are documented.
+
+## Current Status
+
+- The `stream` feature provides `std::io` streaming wrappers.
+- The `tokio` feature is reserved and currently expands to an empty feature set.
+- `scripts/check_reserved_features.sh` verifies that `tokio` remains inert and
+  dependency-free until admission.
+- No async traits, Tokio types, or async runtime dependencies are exported by
+  the crate today.
+
+## Admission Requirements
+
+Before the `tokio` feature may add a dependency or public API, the change must
+include:
+
+- A written dependency review covering the Tokio version, transitive
+  dependency graph, licenses, advisories, and why `std` is insufficient.
+- `tokio` must stay optional and must not become a default feature.
+- The non-async `stream` API must remain available without Tokio.
+- Cancellation behavior must be specified for partially buffered plaintext,
+  encoded output, pending decode input, and terminal padding states.
+- Drop behavior must clear internal staging buffers with the same best-effort
+  retention-reduction posture as the current `std::io` wrappers.
+- Chunk-boundary tests must cover reads and writes split at every Base64
+  quantum boundary.
+- Adjacent framed payload tests must prove decoder readers do not consume bytes
+  beyond terminal padding.
+- Fuzz coverage must include fragmented async-like chunk schedules before any
+  performance claim is made.
+- Release evidence must include `cargo deny check`, `cargo audit`, and
+  `cargo license --json` output with the async feature enabled.
+
+## Non-Goals
+
+- Async wrappers are not a reason to weaken strict Base64 validation.
+- Async wrappers must not enable SIMD dispatch or unsafe code by default.
+- Async wrappers must not become the primary API; caller-owned buffers and
+  scalar strict semantics remain the reference behavior.
+
+## Release Rule
+
+Do not advertise async or Tokio support in release notes until the feature
+exports a tested public API and the dependency/admission evidence is present.

docs/PLAN.md

@@ -83,6 +83,7 @@ Any dependency addition must answer:
 5. `tokio`
    - Reserved feature for future async wrappers.
    - Inert and dependency-free until the async API is admitted.
+   - Admission requirements documented in `docs/ASYNC.md`.
 
 ### API Policy
 

docs/RELEASE.md

@@ -32,6 +32,7 @@ The release gate covers:
 - feature-mode tests
 - Miri no-default-features tests when nightly Miri is installed
 - docs
+- packaged async admission policy while the `tokio` feature remains inert
 - installed cross-target `no_std` checks
 - reserved SIMD feature-bundle compile checks for AVX2, AVX-512 VBMI, and NEON
   when the corresponding Rust targets are installed

docs/RELEASE_EVIDENCE.md

@@ -47,6 +47,8 @@ The release gate runs:
 - `cargo deny check`
 - `cargo audit`
 - `cargo license --json`
+- async admission documentation packaged while the `tokio` feature remains
+  inert and dependency-free
 - Miri when nightly Miri is installed
 - fuzz target compile check when `cargo-fuzz` is installed
 - isolated fuzz and performance harness dependency checks

scripts/validate-release-metadata.sh

@@ -56,6 +56,7 @@ test -s deny.toml
 test -s README.md
 test -s CONTRIBUTING.md
 test -s SECURITY.md
+test -s docs/ASYNC.md
 test -s docs/BENCHMARKS.md
 test -s docs/CONSTANT_TIME.md
 test -s docs/MIGRATION.md
@@ -121,6 +122,7 @@ for required_package_file in \
     "README.md" \
     "rust-toolchain.toml" \
     "SECURITY.md" \
+    "docs/ASYNC.md" \
     "docs/BENCHMARKS.md" \
     "docs/CONSTANT_TIME.md" \
     "docs/MIGRATION.md" \