feat(engine): PRAGMA dispatcher + auto_vacuum knob (SQLR-13)

[joaoh82]

Summary

• Adds the first SQL-level PRAGMA to SQLRite, surfacing the SQLR-10 auto-VACUUM threshold to SDK / FFI / MCP consumers that can't reach Connection::set_auto_vacuum_threshold directly.
• New src/sql/pragma.rs pre-tokenizes PRAGMA statements before sqlparser sees them — sqlparser-rs's pragma-value parser only accepts numbers and quoted strings, so bare OFF / NONE (the classic SQLite idiom) would silently fail without this. Reuses Database::set_auto_vacuum_threshold for range validation; out-of-range values produce a typed error rather than saturating.
• Single-function dispatcher per the task's "switch to a registry when the second pragma lands" guidance.

What's new at the SQL surface

PRAGMA auto_vacuum;            -- read; renders a single-row result set
PRAGMA auto_vacuum = 0.5;      -- arm at 50%
PRAGMA auto_vacuum = 0;        -- arm at 0% (compact on any released page)
PRAGMA auto_vacuum = OFF;      -- disable; equivalent: NONE, 'OFF', 'NONE'
PRAGMA auto_vacuum(0.5);       -- paren form also accepted

Out-of-range numerics, NaN / ±∞, and unknown identifiers like WAL / FULL are rejected with a typed error — the trigger never silently saturates or falls back to a default.

Acceptance criteria (from SQLR-13)

• conn.execute("PRAGMA auto_vacuum = 0.5;") works and is reflected by conn.auto_vacuum_threshold()
• conn.execute("PRAGMA auto_vacuum = OFF;") disables the trigger
• conn.execute("PRAGMA auto_vacuum;") returns a single-row result set (rendered prettytable in CommandOutput.rendered, consistent with how SQLite renders it)
• Out-of-range values produce a typed error, no silent saturation
• New regression tests in src/sql/pager/mod.rs mirror the SQLR-10 setter coverage but routed through SQL

Out of scope (deferred per task description)

• Persisting the threshold in the file header (would require a format-version bump — explicitly noted in SQLR-10 as separate work).
• Connection::prepare("PRAGMA …"). Prepare goes through sqlparser, which rejects bare OFF. Connection::execute is the supported entry point — the AC only requires that path.
• Other SQLite pragmas (journal_mode, synchronous, cache_size, …). Dispatcher is in place; new pragmas plug in as a single match arm in execute_pragma.

Test plan

• cargo build --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --exclude sqlrite-benchmarks --all-targets clean
• cargo fmt --all -- --check clean
• cargo clippy --workspace … no new warnings (pre-existing FFI / MCP warnings unchanged)
• cargo test --workspace … — 501 engine + 19 MCP protocol + others, all green
• 14 new unit tests in src/sql/pragma.rs cover parser shapes, value variants, malformed inputs, and the auto_vacuum handler
• 5 new integration tests in src/sql/pager/mod.rs cover the SQL route end-to-end, including a real auto-VACUUM trigger driven entirely by PRAGMA (OFF keeps file at HWM, high threshold suppresses, re-armed PRAGMA fires after a second drop)

Docs

• README.md — new row in the Supported-SQL quick-reference table
• docs/supported-sql.md — auto-VACUUM section now shows the SQL syntax alongside the Rust setter; "Not yet supported" updated
• docs/pager.md — auto-VACUUM trigger paragraph now points to PRAGMA auto_vacuum
• docs/architecture.md — new module-map row for src/sql/pragma.rs

🤖 Generated with Claude Code