Rename Mode variants A/C to self-describing names #2

New Issue

2026-05-31T18:24:26+02:00

Brummel commented

2026-05-31 18:24:26 +02:00

Concern

The retrieval-mode enum uses opaque single letters: pub enum Mode { C, A } (src/model.rs:58), parsed from the CLI tokens "c" / "a" (src/model.rs:64-65). Neither the code identifier nor the operator-facing token --mode a conveys what the mode does; a reader or operator must consult the design spec to decode them.

What the letters currently encode

The lettering is not arbitrary — it traces a deliberate three-stage axis in the design ledger (docs/specs/2026-05-18-alpha-id-icd-suggestion-design.md:60-63):

C — lexical baseline: BM25 + tag filter, offline, no IONOS calls. The baseline that A must beat.
B — generative-LLM rerank/suggest. Explicitly out of scope and never implemented; the spec states "Modus B ... ist explizit NICHT Scope" (line 63). No enum variant exists for it.
A — hybrid: lexical ∪ semantic pools fused via RRF, then cross-encoder rerank.

Consequence: the A/C gap is meaningful (B is a reserved, deliberately-empty slot), so a rename has to preserve that the two shipped modes sit at opposite ends of a "lexical-only → hybrid" axis rather than being an unordered pair.

Surface a rename touches

Mode enum and its FromStr (src/model.rs:57-69)
CLI --mode flag, default "c", on both suggest and eval (src/bin/alpha_id.rs:22,32)
eval --mode both expansion to [Mode::C, Mode::A] (src/bin/alpha_id.rs:147-148)
Diagnostics mode string format!("{:?}", mode) surfaced in JSON output (src/pipeline.rs:233)
Glossary entries "Mode C" / "Mode A" (docs/glossary.md:23-29)
Spec CLI synopsis --mode c|a (docs/specs/2026-05-18-alpha-id-icd-suggestion-design.md:200,202)
Tests asserting the parse and the variants (tests/model_tests.rs:18-19, tests/pipeline_mode_c_tests.rs, tests/pipeline_mode_a_tests.rs, tests/eval_compare_tests.rs, tests/cli_tests.rs)

The rename has two distinct facets that can be decided independently: the internal Rust identifiers, and the user-facing CLI token plus the diagnostics string (which together form a compatibility surface).

Proposal (unverified — naming to be ratified)

Mode::C → Mode::Lexical, CLI token lexical
Mode::A → Mode::Hybrid, CLI token hybrid

These map directly onto the glossary one-line definitions. Open questions for whoever picks this up:

Keep c / a as accepted CLI aliases for backward compatibility, or hard-switch the tokens?
Does the diagnostics mode field (degraded reporting) need a stable string contract for any downstream consumer (e.g. doctate)?
Confirm the new names still leave conceptual room for the reserved generative tier, should it ever move into scope.

## Concern The retrieval-mode enum uses opaque single letters: `pub enum Mode { C, A }` (`src/model.rs:58`), parsed from the CLI tokens `"c"` / `"a"` (`src/model.rs:64-65`). Neither the code identifier nor the operator-facing token `--mode a` conveys what the mode does; a reader or operator must consult the design spec to decode them. ## What the letters currently encode The lettering is not arbitrary — it traces a deliberate three-stage axis in the design ledger (`docs/specs/2026-05-18-alpha-id-icd-suggestion-design.md:60-63`): - **C** — lexical baseline: BM25 + tag filter, offline, no IONOS calls. The baseline that A must beat. - **B** — generative-LLM rerank/suggest. Explicitly out of scope and never implemented; the spec states "Modus B ... ist explizit NICHT Scope" (line 63). No enum variant exists for it. - **A** — hybrid: lexical ∪ semantic pools fused via RRF, then cross-encoder rerank. Consequence: the A/C gap is meaningful (B is a reserved, deliberately-empty slot), so a rename has to preserve that the two shipped modes sit at opposite ends of a "lexical-only → hybrid" axis rather than being an unordered pair. ## Surface a rename touches - `Mode` enum and its `FromStr` (`src/model.rs:57-69`) - CLI `--mode` flag, default `"c"`, on both `suggest` and `eval` (`src/bin/alpha_id.rs:22,32`) - `eval --mode both` expansion to `[Mode::C, Mode::A]` (`src/bin/alpha_id.rs:147-148`) - Diagnostics mode string `format!("{:?}", mode)` surfaced in JSON output (`src/pipeline.rs:233`) - Glossary entries "Mode C" / "Mode A" (`docs/glossary.md:23-29`) - Spec CLI synopsis `--mode c|a` (`docs/specs/2026-05-18-alpha-id-icd-suggestion-design.md:200,202`) - Tests asserting the parse and the variants (`tests/model_tests.rs:18-19`, `tests/pipeline_mode_c_tests.rs`, `tests/pipeline_mode_a_tests.rs`, `tests/eval_compare_tests.rs`, `tests/cli_tests.rs`) The rename has two distinct facets that can be decided independently: the internal Rust identifiers, and the user-facing CLI token plus the diagnostics string (which together form a compatibility surface). ## Proposal (unverified — naming to be ratified) - `Mode::C` → `Mode::Lexical`, CLI token `lexical` - `Mode::A` → `Mode::Hybrid`, CLI token `hybrid` These map directly onto the glossary one-line definitions. Open questions for whoever picks this up: - [ ] Keep `c` / `a` as accepted CLI aliases for backward compatibility, or hard-switch the tokens? - [ ] Does the diagnostics `mode` field (`degraded` reporting) need a stable string contract for any downstream consumer (e.g. doctate)? - [ ] Confirm the new names still leave conceptual room for the reserved generative tier, should it ever move into scope.

Brummel referenced this issue from a commit

2026-05-31 19:21:54 +02:00

docs: plan for renaming Mode variants A/C (refs #2)

Brummel referenced this issue from a commit

2026-05-31 19:21:54 +02:00

refactor: rename Mode variants C/A to Lexical/Hybrid (closes #2)

Brummel closed this issue

2026-05-31 19:21:54 +02:00

Sign in to join this conversation.