feat: allow injecting Poseidon2 permutations (16/24)

[GrapeBaBa]

Motivation

• Downstream projects sometimes need to use a different Poseidon2 constant set (e.g. spec/test-vector aligned constants) than the default provided by p3_koala_bear::default_koalabear_poseidon2_{16,24}.
• Today, the only option is vendoring/patching this crate to swap the internal Poseidon2 permutation(s), which hurts reproducibility and maintainability.

What this PR does

• Adds opt-in “initialize once” APIs to provide custom Poseidon2 permutations for widths 24 and 16:
  • init_poseidon2_24(perm) / init_poseidon2_16(perm)
  • init_poseidon2_24_with(|| perm) / init_poseidon2_16_with(|| perm)
• Keeps existing behavior as default: if not initialized, the crate continues to lazily use the Plonky3 defaults.
• Returns Poseidon2InitError::AlreadyInitialized { width } if initialization happens after the permutation has already been used/initialized.

Why builder-based APIs

• Avoids forcing callers to construct and pass large constant arrays through public APIs.
• Lets downstream build permutations however they like (from constants, config files, feature-gated code, etc.) while keeping this crate’s surface area small.

Tests

• Adds unit tests covering:
  • Calling init after the permutation is initialized returns AlreadyInitialized
  • Builder is not executed when already initialized

[Copilot]

Pull request overview

This PR adds opt-in APIs for downstream projects to inject custom Poseidon2 permutations (widths 16 and 24) instead of being forced to use the default Plonky3 constants. This improves flexibility for projects that need spec-aligned or test-vector-aligned constants without requiring vendoring or patching.

Key changes:

• Introduces Poseidon2InitError to signal when initialization is attempted after the permutation is already in use
• Adds four public initialization functions: init_poseidon2_24, init_poseidon2_24_with, init_poseidon2_16, and init_poseidon2_16_with
• Provides builder-based APIs (_with variants) to avoid forcing callers to pass large constant arrays through function signatures

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tcoratger]

After leanEthereum/leanSpec#251, it seems to me that the results from Python spec are the same as those obtained in Rust. So I don't think that we need this.

I this the point of making things a bit more flexible but since this library is made only for Ethereum usage, then I don't think that we need this. We prefer here to concentrate only on the constants that matter, and avoid having too many things nearby.

Having this might encourage the user to insert their own constants or permutations, some of which might be unsecure and we want to avoid this.