Brummel
9a81f9eaf7
Records the ratified naming decisions (Lexical/Hybrid, c/a kept as input aliases, diagnostics string free to change — no downstream consumer) and the bite-sized rename task list for the implement step. refs #2 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
75 lines
3.5 KiB
Markdown
75 lines
3.5 KiB
Markdown
# 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).
|