alpha-id/docs/plans/2026-05-31-rename-mode-variants.md

Plan — Rename Mode variants A/C to self-describing names (closes #2)

Context

The retrieval-mode enum uses opaque single letters Mode { C, A } (src/model.rs). Neither the identifier nor the CLI token --mode a conveys intent. The letters trace the design ledger's three-stage axis (docs/specs/2026-05-18-…:60-63): C = lexical baseline (BM25 + tag filter, offline), B = generative rerank (reserved, NOT in scope, no enum variant), A = hybrid (lexical ∪ semantic → RRF → rerank).

Ratified decisions (resolved during this iteration)

• Mode::C → Mode::Lexical, Mode::A → Mode::Hybrid (maps onto the glossary one-line definitions).
• CLI canonical tokens: lexical / hybrid. Keep c / a as accepted input aliases (zero-cost backward compatibility; no external consumer exists, but it protects typed-by-hand invocations).
• Diagnostics mode string (format!("{:?}", mode) in src/pipeline.rs) may change freely to "Lexical" / "Hybrid": verified no downstream consumer parses it. doctate is the future integrator and embeds the library (the Mode enum), not the JSON string (spec §103).
• The reserved generative tier keeps conceptual room: a future Mode::Generative does not collide with Lexical/Hybrid.

Tasks (one cohesive rename — review as a unit)

1. Enum + parser (src/model.rs)

   • Rename variants C → Lexical, A → Hybrid.
   • FromStr: canonical "lexical"/"hybrid"; keep "c"/"a" as accepted aliases (case-insensitive, as today). Unknown → same error.

2. CLI (src/bin/alpha_id.rs)

   • --mode default_value "c" → "lexical" on both Suggest and Eval.
   • eval --mode both expansion vec![Mode::C, Mode::A] → vec![Mode::Lexical, Mode::Hybrid].

3. Pipeline (src/pipeline.rs)

   • Match arms Mode::C/Mode::A → Mode::Lexical/Mode::Hybrid.
   • Rename private methods collect_mode_c → collect_lexical, collect_mode_a → collect_hybrid, and update their doc comments and the inline "Mode C/A" comments to the new names. (Leaving collect_mode_c behind a Mode::Lexical arm would reintroduce the exact opaqueness this issue removes.)

4. Tests

   • git mv tests/pipeline_mode_c_tests.rs tests/pipeline_lexical_tests.rs and …mode_a_tests.rs → …hybrid_tests.rs; update Mode::C/Mode::A and any mode_c/mode_a test-fn names inside to the new names.
   • tests/model_tests.rs: update the parse assertions to the new variants; add an assertion that the c/a aliases still parse (to the new variants) so the alias contract is pinned.

5. Glossary (docs/glossary.md) — record-reality update

   • Headings ### Mode C → ### Mode Lexical, ### Mode A → ### Mode Hybrid. Move the old letter forms into the Avoid lines (Mode C, Modus C, mode c, etc.).
   • Update the cross-references that name "Mode A"/"Mode C" in the RRF, rerank, vector_index, and degrade entries.

6. Spec synopsis (docs/specs/2026-05-18-…:200,202)

   • --mode c|a → --mode lexical|hybrid on both synopsis lines. In-place token edit only; the surrounding German prose is pre-existing and out of scope to translate.

Acceptance

• cargo build and cargo test green.
• alpha-id suggest --mode lexical / --mode hybrid work; --mode c / --mode a still accepted (alias); default is lexical.
• No Mode::C / Mode::A / collect_mode_[ca] / ### Mode C|A references remain anywhere in src, tests, or docs (except as Avoid synonyms in the glossary).