refactor(api): unify EmbeddingRateEncoder with the primary Encoder API

[rmems]

Goal

Remove the split between the crate's primary Encoder / EncodedOutput interface and the separate EmbeddingRateEncoder::forward(&EncoderState) API before 1.0.

The embedding encoder currently introduces its own state and execution vocabulary, which makes the public surface less coherent and increases adapter complexity.

Scope

• Decide whether EmbeddingRateEncoder should implement Encoder, a new explicit stateful-encoder trait, or move into a separate optional module/crate.
• Replace panic-only construction with the crate's standard fallible constructor conventions.
• Define state ownership and reset behavior consistently.
• Validate input/state length mismatches through typed errors.
• Preserve serialization support and migration guidance.
• Update prelude exports and examples.

Design constraints

• Do not weaken the simple Encoder API merely to accommodate one specialized encoder.
• Avoid embedding-model or LLM-specific dependencies and terminology.
• Keep the implementation domain-agnostic.
• Maintain the Tier 2 encoding boundary.

Acceptance criteria

• The embedding encoder follows one documented public trait model.
• Construction and state validation return typed errors where appropriate.
• Reset and streaming semantics are explicit.
• Prelude exports are intentional and consistent.
• Existing behavior has migration tests or documented compatibility notes.
• README contains one end-to-end embedding encoding example.

Relationships

• Depends on feat(api): define explicit spike timestamp and timebase semantics #62 for time semantics.
• Coordinate with feat(api): add allocation-reusing encode_into and SpikeSink interface #63 so the final stateful API can write into caller-owned sinks.
• Blocks the eventual 1.0.0 API freeze.

---

🤖 Authored with ChatGPT: GPT-5.6 (Medium)

[linear-code]

LIM-975

[rmems]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

Refactor EmbeddingRateEncoder to own its membrane state internally and implement the crate's Encoder and ModulatedEncoder traits, replacing the external-state forward(&EncoderState) API.

Replace panic-only and String-based construction with try_new/new and serde validation that use EncoderError variants, including StateLengthMismatch on the deserialization path.

Define explicit deterministic accumulate-and-fire semantics for encode/encode_step and in-place reset. Keep the encoder in its own module to hold the encoding boundary. Make prelude exports explicit.

Remove forward/EncoderState with documented migration notes and equivalence tests. Add one README example plus a runnable examples/embedding_encoding.rs.

Design Choices

Design Choice 1: Which public trait model should EmbeddingRateEncoder follow?

Options Considered:

1. Implement the existing Encoder (and ModulatedEncoder) traits with internal owned state, matching the src/encoders/*.rs pattern.
2. Define a new explicit stateful-encoder trait.
3. Move the encoder into a separate optional module or crate.

Chosen Option: 1

Rationale: This option satisfies the goal to unify with the primary Encoder API. It reuses the established try_new/reset/ModulatedEncoder conventions. It adds no new trait surface, so it does not weaken the simple Encoder API.

Design Choice 2: Where should the per-step drive values come from?

Options Considered:

1. Interpret the encode input slice as the per-step drive values and remove the stored normalized_embeddings field. State becomes only the internal membrane potentials.
2. Keep normalized_embeddings stored as a fixed drive and ignore or override the input parameter.

Chosen Option: 1

Rationale: This option makes the encoder conform to the Encoder trait honestly. It removes the redundant stored input. It keeps the type domain-agnostic. Option 2 leaves the trait input parameter meaningless.

Design Choice 3: What happens to the legacy forward method and EncoderState type?

Options Considered:

1. Remove forward and EncoderState, and document a migration path with equivalence tests.
2. Keep forward and EncoderState as #[deprecated] compatibility wrappers.

Chosen Option: 1

Rationale: The crate is pre-1.0 (0.4.x experimental). The input-driven change makes forward semantically incompatible. Documented migration notes plus equivalence tests satisfy the acceptance criterion. This also removes the EncodedOutput.embeddings versus normalized_embeddings naming overlap.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Conform EmbeddingRateEncoder to the Encoder trait model

This phase changes the encoder's core shape. It moves state inside the encoder. It adds fallible construction with typed errors. It implements the standard trait methods. The goal is a single coherent public trait model that matches the src/encoders/*.rs family.

Task 1: Give the encoder internal state and fallible construction

Move state ownership into the encoder and adopt the standard constructor convention.

• Modify EmbeddingRateEncoder in src/encoder.rs to own an internal membrane_potentials: Vec<f32> field sized to a fixed channel count. Remove the stored normalized_embeddings field.
• Add pub fn try_new(num_channels: usize, config: EmbeddingEncoderConfig) -> Result<Self, EncoderError>.
• Validate config.v_th with a finite-and-positive check that returns EncoderError::NonPositiveOrNonFinite { parameter: "v_th" }. This replaces the current panic!("v_th must be positive") and also rejects NaN/inf.
• Validate num_channels with crate::error::validate_channel_count, which returns EncoderError::NumChannelsTooLarge. This replaces the current assert!.
• Initialize membrane_potentials to vec![0.0; num_channels].
• Keep pub fn new(...) as a thin wrapper that calls try_new(...).expect(...), matching RateEncoder::new.

Task 2: Implement the Encoder trait with explicit reset and streaming semantics

Replace the functional forward API with the trait methods and define state and reset behavior clearly.

• Implement impl Encoder for EmbeddingRateEncoder in src/encoder.rs.
• Add a private helper (for example accumulate_and_fire(&mut self, input, threshold_scale)) that adds each aligned input[i] to membrane_potentials[i], emits a SpikeEvent { channel, timestamp, polarity: true } when the potential reaches the effective threshold, and soft-resets by subtracting the effective threshold. Structure this helper so a future encode_into sink API (issue #63) can reuse it without duplicating spike logic.
• Align input length to the tracked channel count using the sibling convention (truncate longer input via &input[..self.membrane_potentials.len()]; treat shorter input as fewer active channels). This avoids the current u16::try_from(i).expect(...) panic on the hot path, because the channel count is bounded at construction.
• Set the spike timestamp consistently with the crate's current single-step behavior (0) pending the time semantics from issue #62. Do not add a dt_seconds parameter in this ticket.
• Implement encode and encode_step to both delegate to the shared helper. Document explicitly that this encoder is deterministic and integrate-and-fire, that both entry points accumulate into persistent internal state, and that state carries across calls.
• Implement reset(&mut self) to zero membrane_potentials in place without reallocating, matching RateEncoder::reset.
• Remove the old forward method and the EncoderState type from src/encoder.rs.

Task 3: Add ModulatedEncoder support consistent with sibling encoders

Give the encoder the same modulation surface as the rest of the family, without changing the base Encoder API.

• Implement impl ModulatedEncoder for EmbeddingRateEncoder in src/encoder.rs.
• Map the sanitized EncodingGains::threshold_scale onto the effective threshold used by the shared helper, so a higher threshold_scale raises v_th and reduces spiking. Call gains.sanitize() before use, matching RateEncoder::encode_with_gains.
• Implement encode_with_gains and encode_step_with_gains. Rely on the default encode_with_modulators/encode_step_with_modulators implementations from src/lib.rs.
• Do not modify the Encoder or ModulatedEncoder trait definitions in src/lib.rs.

Task 4: Preserve serialization with typed-error validation

Keep the type serde-capable while validating through EncoderError instead of String.

• Update the serde support in src/encoder.rs so the serialized form carries config and the internal membrane_potentials.
• Replace the String-based TryFrom/Repr validation with checks that reuse the same validators as try_new (finite-and-positive v_th via NonPositiveOrNonFinite, channel count via validate_channel_count).
• When deserialized state length is inconsistent with the declared channel count, return EncoderError::StateLengthMismatch { left, right }. This satisfies the typed length-mismatch requirement on the deserialization path.
• Keep all serde code behind #[cfg(feature = "serde")], matching the existing gating.

🤖 Prompt for AI agents

Implement the changes that move `EmbeddingRateEncoder` from a standalone
functional API to the crate's standard `Encoder`/`ModulatedEncoder` trait model.
Work in `src/encoder.rs`.

- Change `EmbeddingRateEncoder` to own an internal `membrane_potentials:
Vec<f32>` field sized to a fixed channel count. Remove the stored
`normalized_embeddings` field.
- Add `pub fn try_new(num_channels: usize, config: EmbeddingEncoderConfig) ->
Result<Self, EncoderError>` that validates `config.v_th` as finite and positive
(returning `EncoderError::NonPositiveOrNonFinite { parameter: "v_th" }` on
failure, replacing the old `panic!`) and validates `num_channels` with
`crate::error::validate_channel_count` (returning
`EncoderError::NumChannelsTooLarge`, replacing the old `assert!`). Initialize
`membrane_potentials` to `vec![0.0; num_channels]`. Keep `pub fn new(...)` as a
thin wrapper around `try_new(...).expect(...)`, matching `RateEncoder::new`.
- Implement `impl Encoder for EmbeddingRateEncoder`. Add a private helper (for
example `accumulate_and_fire(&mut self, input, threshold_scale)`) that adds each
aligned `input[i]` to `membrane_potentials[i]`, emits a `SpikeEvent { channel,
timestamp, polarity: true }` when the potential reaches the effective threshold,
and soft-resets by subtracting the effective threshold. Structure this helper
for reuse by a future `encode_into` sink API without duplicating spike logic.
Align `input` length to the tracked channel count using the sibling convention:
truncate longer input via `&input[..self.membrane_potentials.len()]`, and treat
shorter input as fewer active channels; this avoids the old
`u16::try_from(i).expect(...)` panic since channel count is bounded at
construction. Set the spike `timestamp` to `0`, matching current single-step
behavior. Do not add a `dt_seconds` parameter. Implement `encode` and
`encode_step` to both delegate to the shared helper, and document that the
encoder is deterministic, integrate-and-fire, and that state accumulates
persistently across calls from both entry points. Implement `reset(&mut self)`
to zero `membrane_potentials` in place without reallocating, matching
`RateEncoder::reset`. Remove the old `forward` method and the `EncoderState`
type entirely.
- Implement `impl ModulatedEncoder for EmbeddingRateEncoder`. Map the sanitized
`EncodingGains::threshold_scale` onto the effective threshold used by the shared
helper so a higher `threshold_scale` raises `v_th` and reduces spiking. Call
`gains.sanitize()` before use, matching `RateEncoder::encode_with_gains`.
Implement `encode_with_gains` and `encode_step_with_gains`, relying on the
default `encode_with_modulators`/`encode_step_with_modulators` implementations
in `src/lib.rs`. Do not modify the `Encoder` or `ModulatedEncoder` trait
definitions.
- Update serde support so the serialized form carries `config` and the internal
`membrane_potentials`. Replace the `String`-based `TryFrom`/`Repr` validation
with checks that reuse the same validators as `try_new`. When deserialized state
length does not match the declared channel count, return
`EncoderError::StateLengthMismatch { left, right }`. Keep all serde code behind
`#[cfg(feature = "serde")]`.

Phase 2: Public surface, migration, and tests

This phase makes the public API intentional and proves behavior through tests. It updates the prelude. It removes the now-dead types cleanly. It adds migration, reset, and trait-object tests.

Task 1: Make prelude and module exports intentional

Ensure the public surface exposes only the supported types.

• Update src/lib.rs to re-export EmbeddingRateEncoder and EmbeddingEncoderConfig explicitly from the prelude instead of relying on the pub use crate::encoder::*; glob, so removed types (EncoderState) do not leak.
• Keep EmbeddingRateEncoder in the standalone src/encoder.rs module to maintain the documented encoding boundary between it and the src/encoders/*.rs family. Do not move it into src/encoders/.
• Add a short module-level doc comment in src/encoder.rs that states the boundary rationale and the supported trait model.

Task 2: Add migration, reset, and trait-object tests

Prove the new API behavior and the equivalence with the previous behavior.

• Update the #[cfg(test)] mod tests block in src/encoder.rs. Replace forward/EncoderState tests with tests that call try_new(...).unwrap().encode(&drive).
• Add construction-error tests that assert typed variants, following the delta.rs/derivative.rs pattern: non-positive or non-finite v_th returns NonPositiveOrNonFinite { parameter: "v_th" }; oversized channel count returns NumChannelsTooLarge.
• Add a migration/equivalence test that asserts a fresh encoder driven once by a known vector produces the same spikes that the former forward on a zero state produced. Encode the expected spikes as literals in the test.
• Add a reset test that encodes, calls reset, and asserts membrane_potentials are all 0.0.
• Update tests/serde_tests.rs: adjust the EmbeddingRateEncoder round-trip test to the new serialized shape, remove the EncoderState round-trip test, and update the validation-failure tests to expect the new typed-error deserialization behavior.
• Add a trait-object test (in tests/modulated_encoder_tests.rs or the in-file test module) that drives EmbeddingRateEncoder through &mut dyn Encoder and &mut dyn ModulatedEncoder, mirroring the existing dispatch and streaming-accumulation tests.

🤖 Prompt for AI agents

Update the public API surface and test suite to reflect the new trait-based
`EmbeddingRateEncoder`.

- In `src/lib.rs`, re-export `EmbeddingRateEncoder` and `EmbeddingEncoderConfig`
explicitly from the `prelude`, instead of relying on the `pub use
crate::encoder::*;` glob, so removed types like `EncoderState` do not leak into
the public surface.
- Keep `EmbeddingRateEncoder` in the standalone `src/encoder.rs` module. Do not
move it into `src/encoders/`. Add a short module-level doc comment in
`src/encoder.rs` stating the boundary rationale and the supported trait model.
- Update the `#[cfg(test)] mod tests` block in `src/encoder.rs`: replace
`forward`/`EncoderState` tests with tests calling
`try_new(...).unwrap().encode(&drive)`. Add construction-error tests asserting
typed variants, following the `delta.rs`/`derivative.rs` pattern: non-positive
or non-finite `v_th` returns `NonPositiveOrNonFinite { parameter: "v_th" }`, and
oversized channel count returns `NumChannelsTooLarge`. Add a
migration/equivalence test asserting that a fresh encoder driven once by a known
vector produces the same spikes the former `forward` produced on a zero state,
with expected spikes encoded as literals. Add a reset test that encodes, calls
`reset`, and asserts `membrane_potentials` are all `0.0`.
- Update `tests/serde_tests.rs`: adjust the `EmbeddingRateEncoder` round-trip
test to the new serialized shape, remove the `EncoderState` round-trip test, and
update validation-failure tests to expect the new typed-error deserialization
behavior.
- Add a trait-object test, either in `tests/modulated_encoder_tests.rs` or the
in-file test module, that drives `EmbeddingRateEncoder` through `&mut dyn
Encoder` and `&mut dyn ModulatedEncoder`, mirroring the existing dispatch and
streaming-accumulation tests.

Phase 3: Documentation and example

This phase adds user-facing documentation and one runnable example. It keeps the review checklist in sync.

Task 1: Add an end-to-end embedding encoding example

Provide one runnable example that follows existing example conventions.

• Create examples/embedding_encoding.rs following the skeleton of examples/rate_encoding.rs: a //! banner doc comment, use axon_encoder::prelude::*;, a fn main() with no panics, construction via try_new(...).expect(...), a drive vector, a short loop over steps calling encode (or encode_step), and printed spike counts.
• Register the example in Cargo.toml if example targets are listed explicitly there, and add a cargo run --example embedding_encoding line to the README ## Examples block.

Task 2: Document the embedding encoder and migration guidance

Add the required README section and record the migration path.

• Add one end-to-end embedding encoding section to README.md, styled like the ## Quick start and ### Rate encoder time semantics sections. Show EmbeddingRateEncoder::try_new(...), encode, and reset. Add EmbeddingRateEncoder to the ## Features list.
• Add migration guidance to the README (or the module docs) that maps the old usage EmbeddingRateEncoder::new(&embeddings, config).forward(&EncoderState::new_zeros(n)) to the new usage EmbeddingRateEncoder::try_new(embeddings.len(), config)?.encode(&embeddings), and states that EncoderState and forward are removed.
• Update REVIEW.md's "Examples (behavioral smoke)" list to include the new example, keeping parity with the other encoders.
• Update the rustdoc doctest at the top of EmbeddingRateEncoder in src/encoder.rs to use the new try_new/encode API, because it is a compiled doctest.

🤖 Prompt for AI agents

Add user-facing documentation and a runnable example for the new
`EmbeddingRateEncoder` API.

- Create `examples/embedding_encoding.rs` following the skeleton of
`examples/rate_encoding.rs`: include a `//!` banner doc comment, `use
axon_encoder::prelude::*;`, a `fn main()` with no panics, construction via
`try_new(...).expect(...)`, a drive vector, a short loop over steps calling
`encode` (or `encode_step`), and printed spike counts. Register the example in
`Cargo.toml` if example targets are listed explicitly there. Add a `cargo run
--example embedding_encoding` line to the README `## Examples` block.
- Add one end-to-end embedding encoding section to `README.md`, styled like the
`## Quick start` and `### Rate encoder time semantics` sections. Show
`EmbeddingRateEncoder::try_new(...)`, `encode`, and `reset`. Add
`EmbeddingRateEncoder` to the `## Features` list.
- Add migration guidance to the README (or the module docs) that maps the old
usage `EmbeddingRateEncoder::new(&embeddings,
config).forward(&EncoderState::new_zeros(n))` to the new usage
`EmbeddingRateEncoder::try_new(embeddings.len(), config)?.encode(&embeddings)`,
and states that `EncoderState` and `forward` are removed.
- Update `REVIEW.md`'s "Examples (behavioral smoke)" list to include the new
example, keeping parity with the other encoders.
- Update the rustdoc doctest at the top of `EmbeddingRateEncoder` in
`src/encoder.rs` to use the new `try_new`/`encode` API, since it is a compiled
doctest.

Research

axon-encoder defines the Encoder and ModulatedEncoder traits in src/lib.rs. The main encoder family lives in src/encoders/*.rs. Each encoder there owns its mutable state, exposes a panicking new plus a fallible try_new(...) -> Result<Self, EncoderError>, implements encode/encode_step/reset, and often implements ModulatedEncoder through a shared internal helper. Typed errors and shared validators live in src/error.rs. Gain and modulator types live in src/modulators.rs. EncodedOutput, SpikeEvent, and EncoderConfig live in src/types.rs.

EmbeddingRateEncoder is the outlier. It lives alone in src/encoder.rs (singular). It stores config: EmbeddingEncoderConfig { v_th } and normalized_embeddings: Vec<f32>. It exposes an immutable forward(&self, prev_state: &EncoderState) -> (EncodedOutput, EncoderState) method, a panicking new, and String-based serde validation. It does not implement Encoder or ModulatedEncoder, has no reset, and threads state through the external EncoderState type. Its only consumers are its own unit tests, tests/serde_tests.rs, a rustdoc doctest, and the prelude glob export. It is absent from README, examples, and benchmarks.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the changes that move `EmbeddingRateEncoder` from a standalone
functional API to the crate's standard `Encoder`/`ModulatedEncoder` trait model.
Work in `src/encoder.rs`.

- Change `EmbeddingRateEncoder` to own an internal `membrane_potentials:
Vec<f32>` field sized to a fixed channel count. Remove the stored
`normalized_embeddings` field.
- Add `pub fn try_new(num_channels: usize, config: EmbeddingEncoderConfig) ->
Result<Self, EncoderError>` that validates `config.v_th` as finite and positive
(returning `EncoderError::NonPositiveOrNonFinite { parameter: "v_th" }` on
failure, replacing the old `panic!`) and validates `num_channels` with
`crate::error::validate_channel_count` (returning
`EncoderError::NumChannelsTooLarge`, replacing the old `assert!`). Initialize
`membrane_potentials` to `vec![0.0; num_channels]`. Keep `pub fn new(...)` as a
thin wrapper around `try_new(...).expect(...)`, matching `RateEncoder::new`.
- Implement `impl Encoder for EmbeddingRateEncoder`. Add a private helper (for
example `accumulate_and_fire(&mut self, input, threshold_scale)`) that adds each
aligned `input[i]` to `membrane_potentials[i]`, emits a `SpikeEvent { channel,
timestamp, polarity: true }` when the potential reaches the effective threshold,
and soft-resets by subtracting the effective threshold. Structure this helper
for reuse by a future `encode_into` sink API without duplicating spike logic.
Align `input` length to the tracked channel count using the sibling convention:
truncate longer input via `&input[..self.membrane_potentials.len()]`, and treat
shorter input as fewer active channels; this avoids the old
`u16::try_from(i).expect(...)` panic since channel count is bounded at
construction. Set the spike `timestamp` to `0`, matching current single-step
behavior. Do not add a `dt_seconds` parameter. Implement `encode` and
`encode_step` to both delegate to the shared helper, and document that the
encoder is deterministic, integrate-and-fire, and that state accumulates
persistently across calls from both entry points. Implement `reset(&mut self)`
to zero `membrane_potentials` in place without reallocating, matching
`RateEncoder::reset`. Remove the old `forward` method and the `EncoderState`
type entirely.
- Implement `impl ModulatedEncoder for EmbeddingRateEncoder`. Map the sanitized
`EncodingGains::threshold_scale` onto the effective threshold used by the shared
helper so a higher `threshold_scale` raises `v_th` and reduces spiking. Call
`gains.sanitize()` before use, matching `RateEncoder::encode_with_gains`.
Implement `encode_with_gains` and `encode_step_with_gains`, relying on the
default `encode_with_modulators`/`encode_step_with_modulators` implementations
in `src/lib.rs`. Do not modify the `Encoder` or `ModulatedEncoder` trait
definitions.
- Update serde support so the serialized form carries `config` and the internal
`membrane_potentials`. Replace the `String`-based `TryFrom`/`Repr` validation
with checks that reuse the same validators as `try_new`. When deserialized state
length does not match the declared channel count, return
`EncoderError::StateLengthMismatch { left, right }`. Keep all serde code behind
`#[cfg(feature = "serde")]`.
===============================================================================

Task: 2

Update the public API surface and test suite to reflect the new trait-based
`EmbeddingRateEncoder`.

- In `src/lib.rs`, re-export `EmbeddingRateEncoder` and `EmbeddingEncoderConfig`
explicitly from the `prelude`, instead of relying on the `pub use
crate::encoder::*;` glob, so removed types like `EncoderState` do not leak into
the public surface.
- Keep `EmbeddingRateEncoder` in the standalone `src/encoder.rs` module. Do not
move it into `src/encoders/`. Add a short module-level doc comment in
`src/encoder.rs` stating the boundary rationale and the supported trait model.
- Update the `#[cfg(test)] mod tests` block in `src/encoder.rs`: replace
`forward`/`EncoderState` tests with tests calling
`try_new(...).unwrap().encode(&drive)`. Add construction-error tests asserting
typed variants, following the `delta.rs`/`derivative.rs` pattern: non-positive
or non-finite `v_th` returns `NonPositiveOrNonFinite { parameter: "v_th" }`, and
oversized channel count returns `NumChannelsTooLarge`. Add a
migration/equivalence test asserting that a fresh encoder driven once by a known
vector produces the same spikes the former `forward` produced on a zero state,
with expected spikes encoded as literals. Add a reset test that encodes, calls
`reset`, and asserts `membrane_potentials` are all `0.0`.
- Update `tests/serde_tests.rs`: adjust the `EmbeddingRateEncoder` round-trip
test to the new serialized shape, remove the `EncoderState` round-trip test, and
update validation-failure tests to expect the new typed-error deserialization
behavior.
- Add a trait-object test, either in `tests/modulated_encoder_tests.rs` or the
in-file test module, that drives `EmbeddingRateEncoder` through `&mut dyn
Encoder` and `&mut dyn ModulatedEncoder`, mirroring the existing dispatch and
streaming-accumulation tests.
===============================================================================

Task: 3

Add user-facing documentation and a runnable example for the new
`EmbeddingRateEncoder` API.

- Create `examples/embedding_encoding.rs` following the skeleton of
`examples/rate_encoding.rs`: include a `//!` banner doc comment, `use
axon_encoder::prelude::*;`, a `fn main()` with no panics, construction via
`try_new(...).expect(...)`, a drive vector, a short loop over steps calling
`encode` (or `encode_step`), and printed spike counts. Register the example in
`Cargo.toml` if example targets are listed explicitly there. Add a `cargo run
--example embedding_encoding` line to the README `## Examples` block.
- Add one end-to-end embedding encoding section to `README.md`, styled like the
`## Quick start` and `### Rate encoder time semantics` sections. Show
`EmbeddingRateEncoder::try_new(...)`, `encode`, and `reset`. Add
`EmbeddingRateEncoder` to the `## Features` list.
- Add migration guidance to the README (or the module docs) that maps the old
usage `EmbeddingRateEncoder::new(&embeddings,
config).forward(&EncoderState::new_zeros(n))` to the new usage
`EmbeddingRateEncoder::try_new(embeddings.len(), config)?.encode(&embeddings)`,
and states that `EncoderState` and `forward` are removed.
- Update `REVIEW.md`'s "Examples (behavioral smoke)" list to include the new
example, keeping parity with the other encoders.
- Update the rustdoc doctest at the top of `EmbeddingRateEncoder` in
`src/encoder.rs` to use the new `try_new`/`encode` API, since it is a compiled
doctest.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!