docs improvement for 1.0

[HugoFara]

• Public benchmarks. docs/benchmarks.md with reproducible numbers for the numba solver, PSO throughput, synthesis time.
• Type-stub completeness. Run mypy --strict on src/; close gaps on the public API only.