v0.2.0 — first-class APIs for the 5 v0.1 workspace shims

Breaking release addressing 5 architectural gaps surfaced by the v0.1.1 workspace migration.

Highlights

• TokenAccountPlanConfig — replaces 4-positional-param prepare_token_accounts with a config struct. No Default impl (rent has no safe default); use TokenAccountPlanConfig::with_rent(rent) constructor.
• AtaCreateMode { Idempotent (default), Legacy } — control whether prepare_token_accounts emits idempotent or non-idempotent ATA creates.
• MintIntent::RequireTokenBalance { amount } — validate (not transfer) non-SOL token balance at plan time. Errors with InsufficientBalance instead of v0.1's silent drop.
• TokenMintMetadata — replaces TokenMintWithFee. Now includes program_id (free, from account owner) and transfer_hook_program_id (parsed from TransferHook extension).
• 2 new TokenError variants — InsufficientBalance { mint, required, actual } and RequireBalanceForSolNotSupported(Pubkey).

Migration

See CHANGELOG.md for the full migration guide with before/after code blocks.

Quick summary:

// Before (v0.1.x)
let plan = prepare_token_accounts(&state, &intent, WrapSolStrategy::Ata, rent)?;
let parsed = get_token_mint_and_transfer_fee(pk, &acc, epoch)?;

// After (v0.2.0)
let plan = prepare_token_accounts(&state, &intent, TokenAccountPlanConfig::with_rent(rent))?;
let parsed = get_token_mint_metadata(pk, &acc, epoch)?;

Verification

• cargo +nightly fmt --check — clean
• cargo clippy --all-targets -- -D warnings — clean
• cargo test — 39 pass (15 unit + 18 integration + 6 doc)
• cargo doc --no-deps — clean

Provenance

Designed and shipped via the brainstorm → spec → plan → implement → review workflow. Source documents (in the consuming workspace, not this repo):

• Spec: `docs/superpowers/specs/2026-05-03-solana-token-toolkit-v0.2-design.md`
• Plan: `docs/superpowers/plans/2026-05-03-solana-token-toolkit-v0.2.md`
• Driving review: `docs/superpowers/reviews/2026-05-03-waterpump-token-migration-review.md`