# cached 2.0 → 2.0.1 Migration (Agent Instructions)

Versions: `cached 2.0` → `cached 2.0.1`

`cached_proc_macro` and `cached_proc_macro_types` did not change; leave them pinned
at their existing versions if pinned directly.

## Breaking changes

None. This release is purely additive / a bug fix.

## Behavior fix (no source change required)

### `TtlSortedCacheBuilder` now honors `.capacity()` alongside `.max_size()`

Previously, when both `.max_size(m)` and `.capacity(n)` were set on
`TtlSortedCache::builder()`, the builder reserved `m + 1` slots first and then
`n`. Because `HashMap::reserve` never reduces an existing allocation, a smaller
`.capacity(n)` had no effect — the backing map was always pre-allocated for the
larger `max_size`.

As of 2.0.1, an explicit `.capacity(n)` takes precedence as the preallocation
hint while `.max_size(m)` continues to bound the entry count:

```rust
use cached::stores::TtlSortedCache;
use std::time::Duration;

let cache = TtlSortedCache::<u32, u32>::builder()
    .ttl(Duration::from_secs(300))
    .max_size(65_536) // still caps entry count at 65_536
    .capacity(16)     // now respected: backing map starts small and grows on demand
    .build()
    .unwrap();
```

**Detection:** search for `TtlSortedCache::builder()` (or `.builder()` on a
`TtlSortedCache`) call sites that set both `.max_size(` and `.capacity(`.

**Action:** none required. The fix only changes initial allocation sizing, never
correctness or eviction behavior. Callers that relied on `.capacity()` being
ignored will see a smaller initial allocation; those that want the larger
allocation can set `.capacity(max_size + 1)` explicitly.

Note: `TtlSortedCache::set_max_size` / `try_set_max_size` on a live cache still
re-grow the backing map to `max_size + 1`, overriding a smaller build-time
`capacity`.

## Required Cargo.toml change

```toml
# Before
cached = "2.0"

# After
cached = "2.0.1"
```

## VERIFY

`cargo build` — no new compile errors expected from the version bump.

`cargo test --features time_stores` — exercises the `TtlSortedCache` builder,
including the new regression tests for the `capacity` / `max_size` interaction.
