# v0.11.0 — 1.0 Documentation Set

**Release date:** 2026-05-23
**Status:** the final pre-1.0 release. Source-level surface is
unchanged from 0.10.0; this is the phase that writes down the
1.0 contract so 1.0.0 itself can be the deliberate stable cut.

---

## What this release is

Documentation. Specifically, the five docs the ROADMAP listed as
prerequisites for 1.0:

- **`docs/STABILITY-1.0.md`** — what 1.0 freezes, the MSRV
  policy, what changes in 1.x vs 2.0, the migration commitment.
- **`docs/ARCHITECTURE.md`** — module layout, algorithm dispatch
  pattern, dependency rationale, trust boundaries, out-of-scope
  list.
- **`docs/SECURITY.md`** — threat model, algorithm choices,
  vulnerability reporting, verification posture, known caveats.
- **`docs/PLATFORM-NOTES.md`** — per-platform hardware-
  acceleration availability, OS specifics, cross-compile guide,
  pick-by-platform cheatsheet.
- **`docs/FILE_FORMAT.md`** — stream wire format normative spec
  (frozen for the 1.x series).

Existing docs already in place from previous phases (`API.md`,
`PERFORMANCE.md`, `CHANGELOG.md`, per-release notes) are all
current and cross-linked from the README's documentation index.

**No source-level changes vs 0.10.0.** All public types,
methods, behaviors, and wire formats carry forward. This release
exists so the docs land as their own shippable artifact and 1.0
can be a clean cut.

---

## What's new

### `docs/STABILITY-1.0.md`

The 1.0 stability contract. Every item that will be frozen at
1.0 is listed with its frozen signature. The MSRV policy
(Rust 1.85 for 1.0; MSRV raises are minor-version events).
What can change in 1.x (additive only — new `Algorithm` /
`Error` variants, new methods, new module surface, performance
improvements). What requires a 2.0 (any removal, rename,
behavior change, wire-format break, default-feature drop).
Migration policy (1.x → 2.x ships with a `MIGRATION.md`; old
1.x receives security patches for at least 12 months).

### `docs/ARCHITECTURE.md`

How the crate is organised internally. Module-by-module
responsibilities, the algorithm dispatch pattern (so adding a
new `Algorithm` in 1.x is mechanically simple), the error-
handling design (why `AuthenticationFailed` is opaque), the
dependency rationale (every dep justified), the build profiles
(why `lto = "fat"`), and the canonical out-of-scope list.

### `docs/SECURITY.md`

The threat model spelled out. What `crypt-io` protects against
(tampering, wrong-key decryption, AAD mismatch, header
tampering, stream-protocol attacks via STREAM construction,
timing side-channels on tag comparison). What's out of scope
(side channels beyond timing, compromised endpoints, key
generation/storage/rotation, quantum attackers). The trust
boundaries (the key you pass in is trusted; the ciphertext is
attacker-controlled). Vulnerability reporting to
`security@hivedb.com`. The known caveats — Argon2id defaults
age with hardware; no nonce-misuse resistance in 1.0; encrypt
allocating-path slower than `_into` for hot loops.

### `docs/PLATFORM-NOTES.md`

Where the algorithms get hardware acceleration and where they
don't. The full matrix:

- x86_64 with AES-NI + SHA-NI (Intel Ice Lake+, AMD Zen 3+) →
  AES-GCM + SHA-256 both hardware-accelerated.
- ARMv8 with crypto extensions (modern Apple Silicon, AWS
  Graviton 2+) → same picture.
- Platforms without crypto instructions (older ARM, RISC-V,
  pre-2010 x86) → ChaCha20-Poly1305 is the correct AEAD choice;
  BLAKE3 wins for hashing because its SIMD path runs on any
  modern vector unit.

Includes an OS-specifics section (Linux / macOS / Windows
nonce-source detail, no special permissions needed, line-ending
behaviour) and a cross-compile guide.

### `docs/FILE_FORMAT.md`

The stream wire format, normatively. Byte-by-byte header
layout, per-chunk nonce derivation (the STREAM construction
with the last-flag byte), the final-chunk-always invariant,
validation rules, two worked examples (100-byte and
exact-multiple plaintexts), counter overflow handling
(`2^32` chunks per stream = 256 TiB at default chunk size),
and the 1.x compatibility commitment (wire format frozen; new
`Algorithm` variants get new bytes; reserved bytes stay
reserved).

---

## What's NOT in 0.11.0

- **`1.0.0` itself.** The version bumps to `0.11.0`, not `1.0.0`
  — see "Why 0.11.0 not 1.0.0" below.
- **No new code.** Zero source-level changes vs 0.10.0.

---

## Why 0.11.0, not 1.0.0

This release ships the docs that 1.0 requires; it doesn't ship
1.0 itself. Two reasons for the gap:

1. **1.0 deserves its own release notes.** The 0.x → 1.0 story
   is worth consolidating in one place for first-time crates.io
   readers who didn't see the per-phase notes. Drafting those
   notes is the work of the 1.0 cut, not the docs phase.
2. **1.0 deserves the 1-CPU-hour-per-target fuzz soak.** The
   0.9.0 release notes flagged this as the gate before the
   stable cut. Smoke results (4.7 M iterations across 8 targets,
   0 findings) are encouraging but not sufficient; the long
   soak validates stability under extended pressure.

The next phase ship is **1.0.0** itself. Pre-flight checklist
in [`.dev/ROADMAP.md`](.dev/ROADMAP.md).

---

## Compatibility & build

- **Fully backwards compatible.** All 0.10.0 public API carries
  forward unchanged.
- **No new dependencies.**
- **MSRV unchanged:** Rust 1.85 (edition 2024).
- **Default features unchanged.**

---

## Installation

```toml
[dependencies]
crypt-io = "0.11"
```

---

## Verification

| Check | Result |
|---|---|
| `cargo fmt --all -- --check` (Windows + WSL Linux) | clean |
| `cargo clippy --all-targets --all-features -- -D warnings` (both) | clean |
| `cargo test --all-features` (both) | 126 unit + 12 `_into` + 1 smoke + 25 stream + 33 doctest — all passing |
| `cargo doc --no-deps --all-features` with `RUSTDOCFLAGS="-D warnings"` (both) | clean — every public item documented |
| MSRV (1.85) build | clean |
| `cargo-fuzz` smoke (carried forward from 0.9.0) | 8 targets clean |
| All 5 examples run | passes |

---

## What's next

Phase 1.0.0: stable release. Run the 1-CPU-hour-per-target fuzz
soak (~8 hours unattended on WSL). One-week external review
window. Draft `docs/release/v1.0.0.md` consolidating the 0.x →
1.0 story. Bump `Cargo.toml` to `1.0.0`. Tag. Publish. Pre-flight
checklist in [`.dev/ROADMAP.md`](.dev/ROADMAP.md).
