feat(sql): JOINs — INNER / LEFT / RIGHT / FULL OUTER (SQLR-5)

[joaoh82]

Summary

• Implements the four-flavor JOIN quartet (INNER, LEFT OUTER, RIGHT OUTER, FULL OUTER) with explicit ON conditions and table aliases.
• SQLite ships only INNER and LEFT OUTER; we ship all four because the per-flavor delta on top of a shared nested-loop driver is just NULL-padding policy. See docs/design-decisions.md §14a for the reasoning.
• Adds a RowScope trait so the existing single-table fast path is preserved verbatim while JoinedScope handles multi-table resolution with proper NULL padding.

What changed

Engine (src/sql/executor.rs)

• New RowScope trait + SingleTableScope (legacy) and JoinedScope (multi-table) implementations.
• eval_expr / eval_predicate / eval_function / json_fn_* / FTS helpers / vector-arg extractor refactored to take &dyn RowScope.
• execute_select_rows_joined: left-folded nested-loop driver, O(N×M) per join level. ON only sees tables in scope at that join level (forward references error). ON reuses eval_predicate_scope so non-zero ints are truthy, matching WHERE.

Parser (src/sql/parser/select.rs)

• SelectQuery gains table_alias and joins: Vec<JoinClause>.
• ProjectionKind::Column carries an optional qualifier so t.col references can disambiguate across tables.
• USING / NATURAL / CROSS / comma joins surface as NotImplemented.
• Aggregates / GROUP BY / DISTINCT over JOIN rejected at parse time.

Tests: 17 new tests covering all four flavors, NULL padding both directions, qualified/unqualified column resolution, ambiguity detection, self-join rejection, three-table chaining, chained LEFT OUTER, NULL ordering on outer joins, ON-references-later-table errors, and truthy-int ON. Total 526 tests passing, 0 failures.

Docs: README.md, docs/supported-sql.md (new "JOIN semantics" section + per-flavor table), docs/design-decisions.md (§14a rationale), docs/architecture.md, docs/sql-engine.md all updated.

Caveats / follow-ups (filed separately)

• JoinedScope errors on missing/ambiguous columns while SingleTableScope returns Value::Null — long-standing inconsistency, project-wide.
• Many JoinedScope errors classify as SQLRiteError::Internal when they're really user-input issues.
• Allocation pressure in the inner join loop is 2·N·M heap allocs; reusable scratch buffer is a future optimization.
• JOIN ... USING and NATURAL JOIN still NotImplemented.
• Aggregates / GROUP BY / DISTINCT over JOIN need wiring through the existing aggregator.

Test plan

• cargo build --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --all-targets
• cargo test --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs — 526 pass, 0 fail
• cargo fmt --all -- --check
• cargo clippy --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --all-targets — no new warnings
• REPL smoke-tested LEFT OUTER and FULL OUTER on a customers/orders fixture

🤖 Generated with Claude Code