fix(cli): an untouched session leaves [search] in force, and .bench runs at the quality it prints (#2303)

[cyberlife-coder]

Fixes #2303

Both items ship together because they are one rule. Item 1 decides what an untouched session searches at, and .bench (item 2) has to search at that same quality. Landing item 2 alone would have made .bench force balanced too.

Item 1: an untouched session leaves [search] in force

Decision. The configuration priority order documented in docs/guides/CONFIGURATION.md wins: file < runtime override, where the runtime override is "REPL \set, VelesQL WITH, API params". A session default nobody chose is not a \set.

The investigation comment on #2303 notes that repl_execute_tests.rs asserted the opposite on purpose (an untouched session injects mode = 'balanced') and asks that a change to it be deliberate. This PR is that change. The test and its doc comment are rewritten, with the documented priority order as the reason.

• SessionSettings.mode is now Option<SearchQuality>. None means never \set.
  • search_quality() returns the session's ef_search (as Custom, which is exactly what core's search_with_ef runs), else its mode, else None.
  • mode_str() returns an Option.
  • \reset mode and \reset go back to None rather than to balanced.
  • The mode() and test-only effective_ef_search() getters are gone. Tests read search_quality() and get(...).
• The query path (inject_session_with_options) adds the session's quality only when it holds one. When it holds none it adds nothing, not even an empty WITH, so the search reaches self.search and the collection's runtime quality.
• \show takes the database and prints the configured default for an unset mode, as fast (configured default), using db.config().search.resolved_quality(). ef_search shows auto (…) for the mode in force.
• .help, CLI_REPL_REFERENCE.md and CONFIGURATION.md say so.

Item 2: .bench runs at the quality it prints

.bench printed mode={:?} but called col.search(&query, k). It now searches with col.search_with_quality(q, k, quality) when the session sets a quality, and with col.search(q, k) otherwise, which applies the configured default. It prints the quality it runs at. It also used to drop every failed query (if let Ok), so a bench whose queries were all refused still reported a throughput. The first error now ends it with query i of n failed: ….

Red first

• .bench: with the new tests run against the old .bench code, bench_runs_at_the_session_mode_and_reports_the_refusal failed with ".bench at mode perfect ran past the Perfect-mode cap", on seed_docs_refusing_perfect: max_perfect_mode_vectors = 1, 3 points.
• Item 1: before this change, test_session_ef_search_reaches_the_search pinned [("mode", "balanced")] for an untouched session. It now pins []. The new test_an_untouched_session_leaves_the_configured_quality_in_force asserts that the parsed query keeps no WITH clause.
• Mutations, each run against this branch:
  • An untouched session injecting mode = 'balanced' again fails test_an_untouched_session_leaves_the_configured_quality_in_force and test_session_ef_search_reaches_the_search.
  • A search_quality() that returns the mode alone, ignoring ef_search, fails bench_runs_at_the_session_ef_search_over_its_mode ("the session ef_search was ignored"), plus two session tests.

Review round 1

• \show and .bench read the configured default untested. Hard-coding balanced in either left every test green. Both now go through a helper, shown_settings(db, session, key) for \show and bench_quality(db, session) for .bench. Each helper returns what the command prints, and the new tests call it on a database opened through the CLI's --config path with [search] default_mode = "fast". Two mutations each fail their test: show_prints_the_configured_default_for_an_unset_mode and bench_at_an_untouched_session_prints_the_configured_default. That second test replaces bench_at_an_untouched_session_runs_every_query, which also passed on develop's .bench.
• .bench on an untouched session still calls col.search. That is the same call a query from an untouched session makes, and search_with_opts falls back to it. It uses the PQ/ADC path, and search_with_quality does not, so routing through search_with_quality(resolved_quality()) would change what a bench measures on a PQ collection. Which quality col.search runs at is the collection's runtime quality, pushed from [search].resolved_quality(). The bench prints that same value, and a test pins it. No test-sized collection can tell col.search apart from a balanced search at that point: a configured perfect default is applied as accurate, so the Perfect cap never shows.
• Docs. Without --config, the CLI does not read ./velesdb.toml (cli: ./velesdb.toml is not read without --config, although CONFIGURATION.md says it is #2400). So .help and CLI_REPL_REFERENCE.md now say an unset mode takes the [search] of the --config/VELESDB_CONFIG file. The .bench row names the configured default as its last fallback.
• Fixtures. seed_docs, seed_docs_refusing_perfect and the new seed_docs_configured move to a #[cfg(test)] mod test_fixtures, which the three REPL test files use (repl_execute_tests.rs, repl_data_cmds_tests.rs, repl_config_cmds_tests.rs). It lives in repl_fixtures_tests.rs. CI's check_prod_unwraps.py exempts test-named paths (*_tests.rs, *_test.rs, tests/, benches/), and #[test] functions and #[cfg(test)] items inside the file it scans. It checks each file on its own, so a file whose only test gate is its mod line in main.rs counts as production. That is why it failed Lint & Format on ff7ff59, while the file was named test_fixtures.rs. repl_execute_tests is private again.

Review round 2

• Wording. The CHANGELOG entry and the comments on inject_session_with_options and SessionSettings.mode now name the --config/VELESDB_CONFIG file and cli: ./velesdb.toml is not read without --config, although CONFIGURATION.md says it is #2400, as .help and the reference already do.
• Test name. The bench test is renamed bench_at_an_untouched_session_prints_the_configured_default, and its doc says that it leaves the search arm unpinned on purpose.
• Counts. The Gates section no longer carries a hard-coded test count.

Found on the way, filed rather than widened

• core: a search that sets only rerank runs at Balanced, not the configured [search] default #2399: a core search whose options set only rerank runs at Balanced, not the configured default (SearchOptions::resolved_quality).
• cli: ./velesdb.toml is not read without --config, although CONFIGURATION.md says it is #2400: the CLI never reads ./velesdb.toml without --config, although CONFIGURATION.md says it does. Until that is fixed, item 1 only helps a user whose file is loaded through --config/VELESDB_CONFIG.

Gates (local, aarch64; reduced to the changed crate to spare the machine, CI runs the whole workspace)

• cargo fmt --all -- --check; cargo clippy -p velesdb-cli --all-targets -- -D warnings -D clippy::pedantic
• cargo test -p velesdb-cli --bin velesdb: all pass
• check-inline-tests, check-file-budgets, check-doc-freshness, check-feature-claims, check-ai-attribution

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 4 complexity

Metric	Results
Complexity	4

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}