release: v0.1.0 final polish — API freeze, doc truth, offline benches, live-verified

[KaiCode2]

Closes out every finding from the full pre-release review (docs, API surface, tests, benches, release mechanics) so v0.1.0 can be re-tagged and published from a state where nothing cheap-to-fix-now becomes breaking-later.

API surface (free today, breaking once a downstream exists)

• sol! bindings privatized — module-scope sol! generates pub items, so ~30 internal ABI types (quote-call structs, event decls, factory events) rendered on docs.rs as public API. Each block now lives in a crate-internal mod abi (the existing pancake_v3/solidly_events idiom); the RPC-parity/WS tests that borrowed them declare their own local ground-truth ABI.
• Public deps re-exported — pub use evm_fork_cache; + pub use alloy_primitives; at the root, with the 0.x lockstep policy documented: downstream no longer hand-pins matching versions to name EvmCache or Address.
• docs.rs feature badges — rustdoc-args = ["--cfg", "docsrs"] + feature(doc_cfg) (post-1.92 auto-cfg): gated modules/items now render "Available on crate feature …" badges.
• #[non_exhaustive] gaps closed on the cold_start/bytecode/state mirror structs (with documented constructors — ColdStartPlan already had a pending upstream probe_roots field waiting to break planner authors), BytecodeTemplateError joins the other error enums, SlotDelta documents why it deliberately stays exhaustive.
• Small doc-truth on API: find_many's doc-merge artifact (stale block was the rustdoc summary), simulate_swap's stale from = ZERO claim, V3StorageLayout/SolidlyStorageLayout exported at the root unconditionally.

Shipped-docs truth pass

• The last merge train outran four shipped docs: CHANGELOG [0.1.0], README (intro + protocol table), protocol-support-matrix.md, and trace-backed-sync.md all still said Balancer Swap → resync (pre-Event-source Balancer V2 swaps #33) — now they describe the event-sourced exact cash writes, and the changelog gains the omitted features (Event-source Balancer V2 swaps #33 event-sourcing, perf(cold-start): verify-only fast path for Curve + Balancer (+ optional Curve code seed) #31 verify-only fast path, CurveMetadata::with_code_seed, Balancer/Curve cold_start_many bundling, the new stateDiff parity suites).
• Ghost mechanism removed: README/pool-discovery.md/CHANGELOG still described the MetaRegistry/ViewCall discovery mechanism dropped in 3a197f3.
• Guides: writing-an-adapter table gains the missing pool_factories/code_seeds rows ("six defaulted" → nine), high-performance-bootstrap-defaults past-tenses its superseded narrative and marks checklist item 1 done, benchmarks.md no longer promises HTML reports this build can't produce (no plotters backend), iteration-count and CU figures are consistent everywhere (one auditable derivation: 7,674 × 17 CU).

README storefront

Badges (crates.io / docs.rs / CI / license / MSRV), an Installation section (cargo add, feature trimming, MSRV 1.88, re-export policy), a 12-example index with a zero-setup "start here" (custom_adapter), the Slipstream quoting caveat surfaced beside the Solidly one, and the quickstart now compiles as a doctest (cfg(doctest) README include; rust,ignore → rust,no_run).

Tests & benches

• Exact-boundary unit tests for the new packed-word arithmetic: V3 gross/net at u128::MAX/i128 limits, Balancer cash at the 2^112 field edges — pinning checked-None (resync) semantics, never wrap/saturate/carry into a co-tenant field.
• Solidly V2 joins the AmmSyncEngine coverage (was the only protocol with no engine/WS test): a Sync applies as two exact writes with zero resync work, proven by panicking trace/storage fetchers.
• New fully-offline benches/reactive_apply.rs (mock-backed cache, pre-warmed packed words — no env, runs in CI): measures every event-sourced apply path end-to-end through AdapterDriver::apply_log. Measured (July 2026, M-series host): V2 Sync ~283 ns, Balancer swap ~432 ns (TWO_TOKEN) / ~519 ns (GENERAL), V3 Mint/Burn ~1.4 µs. benchmarks.md's reactive table now carries all five paths instead of extrapolating from the single V2 row.
• The two publicnode-fallback examples warn up front that free endpoints can rate-limit the run mid-way.

Release mechanics

• .cargo/audit.toml: cargo audit is green with the one lockfile-only advisory (RUSTSEC-2025-0055, tracing-subscriber 0.2.25 via revm-precompile's optional, never-enabled arkworks backend) ignored with the justification checked in.
• RELEASING.md: live suites are now a required release step covering all eight gated files (was "optional", naming three), package facts refreshed (56 files / seven guides), and the tag section documents the re-point procedure this release needs (the pushed v0.1.0 tag sits six merges behind main).
• ROADMAP.md: factory discovery shipped in 0.1.0 (the plan still promised it for 0.2.0 under pre-implementation API names); 0.1.x/0.2.0 now lists the real candidates (PR perf(cold-start): eth_createAccessList two-shot warming for fast first boot #32 access-list warming — deliberately deferred, Balancer log-scan + Curve MetaRegistry discovery, PoolBalanceManaged subscription, Algebra forks, Bootstrapper, incremental interests).
• A scheduled + on-demand live-test workflow (live.yml: weekly cargo test --all-features -- --ignored with the E2E_RPC_URL secret, plus a cargo-audit job) is ready on a separate branch — the gh token lacks workflow scope, so it needs an SSH push (see PR comment).
• One real bug found by this PR's own gates: deleting an import orphaned its #[cfg] attribute in factory.rs, hiding ProtocolMetadata from solidly-only builds — caught by the isolation clippy matrix, fixed here.

Verification

Full battery on a clean tree, all green (22 checks):

• cargo fmt --check; clippy -D warnings on all-features, no-default, and the 7-way per-protocol isolation matrix (which caught the orphaned-cfg bug above)
• cargo test on all-features / default / no-default (198 offline tests + the README doctest)
• docs -D warnings on stable (CI parity) and nightly --cfg docsrs (docs.rs parity — feature badges verified in the rendered HTML)
• cargo +1.88 check --all-features (MSRV), experimental-protocols both bare and stacked
• cargo audit (green with the checked-in policy), heavy-dep guard, cargo package --list (56 files), cargo publish --dry-run
• cargo bench --bench reactive_apply runs offline and produced the numbers cited above

And the full live gate against an archive endpoint (cargo test --all-features -- --ignored): 25/25 passed, 0 failures — per-protocol quote parity (mainnet + Base), factory base-slot/CREATE2 constants, one-shot V3 sync parity, both per-transaction stateDiff write-parity suites for the event-sourced paths, and both live WS soaks (~190 s / ~302 s of real mainnet events applied with exact writes).

Not in this PR: live.yml (the scheduled live-test + audit workflow) — the gh token lacks workflow scope, so it rides the local ci/live-tests branch and needs one SSH push once the 1Password agent behaves. PR #32 (access-list warming) stays deferred to 0.1.x by design.

After merge: re-point the v0.1.0 tag at the merge commit (it currently sits six merges behind on 6187d50), then cargo publish.

🤖 Generated with Claude Code