Close retain cursor optimization audit

[tomsanbear]

Summary

• pre-register and complete the cross-platform retain audit
• record three rejected loop/copy candidates and one rejected conditional layout candidate
• preserve exact seven-round Linux Ryzen and M3 Pro evidence for scalar and 64-byte retain
• retain the canonical guarded two-phase implementation after exhausting measured mechanisms

Findings

• focused JackVec u64 retain is already at Vec parity or better on both hosts
• a unified cursor loop regresses both platforms
• pointer caching is optimized away on M3 and inconclusive on Linux
• aligned-middle copying produces only a sub-threshold M3 gain with Linux/layout regressions
• conditional 16-byte large-element alignment regresses Linux and is neutral on M3
• isolated AArch64 wrappers emit the same predicate and 64-byte relocation instructions for JackVec and Vec

Validation

• stable all-target tests, no-std feature checks, MSRV 1.86
• Clippy and rustdoc with warnings denied
• strict-provenance Tree Borrows Miri: 111 tests and 49 doctests
• benchmark runner and reporting tests
• final src/lib.rs is identical to canonical main

Raw paired artifacts remain on the two benchmark hosts under the versioned retain-* directories.

[codspeed-hq]

Merging this PR will not alter performance

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 2 improved benchmarks
❌ 2 regressed benchmarks
✅ 106 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	ThinVec[4]	132.5 ns	161.7 ns	-18.04%
❌	JackVec[4]	192.5 ns	221.7 ns	-13.16%
⚡	SmallVec4[4]	174.4 ns	145.3 ns	+20.08%
⚡	SmallVec8[8]	277.5 ns	248.3 ns	+11.74%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing perf/retain-cursor-audit (20b5e3e) with main (323ae2f)}