fix(sql): validate table qualifiers in FTS function column args (SQLR-15)

[joaoh82]

Problem

SQLR-14 (#167) made single-table scope reject unknown table qualifiers in plain column references, but fts_match / bm25_score extract their column argument syntactically (they need the column name to find the FTS index, not its value), so the qualifier never went through RowScope::lookup:

SELECT id FROM docs WHERE fts_match(bogus.body, 'rust');          -- worked; 'bogus.' silently dropped
SELECT id FROM docs ORDER BY bm25_score(bogus.body, 'rust') DESC; -- same (scalar-eval path)

This was the explicitly-deferred gap in #167's "Known gaps".

Fix

• Add scope_name(&self) -> Option<&str> to the RowScope trait — Some(alias-or-table-name) for SingleTableScope, None for JoinedScope (per-qualifier resolution happens in lookup) and GroupRowScope (output rows carry no qualifier).
• resolve_fts_args now runs check_single_scope_qualifier on a two-part CompoundIdentifier column arg, producing the SQLR-14 wording: unknown table qualifier '<q>' in column reference '<q>.<col>'. Identifiers with 3+ parts now error like the main evaluator instead of silently truncating.

The optimizer probes (try_fts_probe, identify_indexed_arg_and_literal) only match bare identifiers, so qualified args always take the scalar path — which now validates.

Audit of other syntactic extraction sites (per acceptance criteria)

• JSON functions, vec_distance_* — no gap: their args are evaluated through eval_expr_scope → scope.lookup, which already runs the SQLR-14 check.
• Pager catalog re-parses (pager/mod.rs) — trusted engine-written sqlrite_master SQL, not user input. No change.
• Two real gaps in other statement contexts, filed as follow-ups: marvinapp SQLR Rename crate to sqlrite-engine on crates.io #17 (CREATE INDEX ix ON t (bogus.col) strips qualifier) and SQLR Release v0.1.2 #18 (aggregating-path ORDER BY bogus.name strips qualifier when matching output columns).

Tests

7 new end-to-end tests in src/sql/mod.rs covering the acceptance matrix: matching table-name qualifier (incl. case-insensitive), matching alias, alias-shadows-table-name, bogus qualifier in WHERE (fts_match), WHERE-comparison and ORDER BY (bm25_score), and a ranking test proving qualified args still produce correct top-k via the scalar path. The three negative tests fail on the unfixed executor and pass with the fix.

Full verification: workspace test suite (CI exclusions) all green, cargo fmt --check clean, clippy/doc warnings unchanged (pre-existing, none on changed code). REPL + file-backed save/reopen smoke checks pass.

Docs

• docs/supported-sql.md — qualified-references bullet now covers FTS function args (SQLR-15)
• docs/fts.md — qualified-arg behavior documented for both functions, plus a note that qualified args skip the optimizer probe
• docs/sql-engine.md — expression-evaluator section mentions the RowScope::scope_name() path

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
rust-sqlite	Ready	Preview, Comment	Jun 11, 2026 2:36pm