[P1][arch] Single execute_query IPC entry point — ARCHITECTURE §5 declares 35 commands, 13 unimplemented + 22 undocumented in §5

[EVWorth]

Context

docs/design/ARCHITECTURE.md §5 declares the full Tauri command surface. The implementation registers only a subset, and per-feature audits have repeatedly flagged the gap.

Problem

ARCHITECTURE §5 declares 32 commands. invoke_handler![] in src-tauri/src/lib.rs:184-225 registers 41 commands (28 in commands/mod.rs + 5 in commands/ai.rs + 8 in commands/sqlite.rs). 13 declared commands are unimplemented:

§5 section	Missing command	Per-feature audit issue
§5.2 Query	execute_query_stream	#284 (editor.md F4 — streaming not implemented)
§5.2	cancel_query	#281 (editor.md F1 — Cancel is JS-counter only)
§5.2	explain_query (folded into resultStore)	#412, #418 (explain.md F1, F2 — EXPLAIN ANALYZE bypasses safety)
§5.2	format_sql	not filed (frontend uses sql-formatter npm)
§5.2	get_query_history	#324 (history.md F1 — no backend history at all)
§5.3 Schema	get_foreign_keys	not filed (consumers don't need it)
§5.3	refresh_schema	not filed (refresh is client-side cache clear)
§5.4 AI	ai_generate_sql	#310 (ai.md F3 — 3 missing AI commands)
§5.4	ai_explain_query	#310
§5.4	ai_optimize_query	#310
§5.5 Export	export_data	not filed as P1; #363 covers import side
§5.5 Import	import_data	#363 (import.md F1 — ARCHITECTURE 5.5 declares commands, none exist)
§5.5	preview_import	#363
§5.6 Admin	get_users	#429, #445 (admin.md F1, F8 — routes through execute_query, no tests)
§5.6	get_server_status	not filed (computed in JS from SHOW STATUS)
§5.6	table_maintenance	not filed

22 commands are registered but undocumented in ARCHITECTURE §5 (file-IO: read_file_contents, pick_file, write_file_contents, pick_save_file; platform: is_rpm_ostree; SQLite: 8 commands; AI extras: ai_set_config, ai_cancel, ai_approve_permission).

The single execute_query entry point is the backend counterpart to frontend god-component smell: every feature routes through it. This blocks:

• Per-feature read_only gating ([P1][security] read_only profile flag is UI-only — backend executes DML/DDL unrestricted (FR-1.2.7) #277 — read_only profile flag UI-only).
• Streaming ([P1][doc-drift] Streaming/event architecture described in ARCHITECTURE is not implemented #284) and cancellation ([P0][bug] cancel is JS-counter only; no KILL QUERY; ARCHITECTURE §5.2 cancel_query unimplemented #281).
• Proper import/export boundaries ([P0][doc-drift] ARCHITECTURE 5.5 declares import_data, preview_import, export_data Rust commands — none exist #363).
• Admin-user CRUD with audit ([P0] [security] User CRUD/GRANT/REVOKE go through execute_query — no read_only, no audit, no transaction #429).
• AI command surface ([P0][doc-drift] ARCHITECTURE §5.4 lists 5 AI commands; ai_generate_sql / ai_explain_query / ai_optimize_query don't exist #310).

The cross-cutting audit (docs/audits/cross-cutting.md F12) flagged this as P1. This is the unifying architectural refactor.

Files

• docs/design/ARCHITECTURE.md:952-998 (§5.2), 999-1076 (§5.3), 1079-1119 (§5.4), 1121-1147 (§5.5), 1149-1199 (§5.6)
• src-tauri/src/lib.rs:184-225 (invoke_handler!)
• src-tauri/src/commands/mod.rs:157-181 (the single execute_query)
• All consumer files listed in F2 above

Repro

grep -c "tauri::command" src-tauri/src/commands/*.rs  # 41 registered
grep -E "async fn " docs/design/ARCHITECTURE.md | grep -v "///\|//" | wc -l  # 32 declared

Expected

Per-feature command variants and the missing declared commands all exist:

• run_select_query (read-only fast path; already exists inside mas-ai/tools.rs but is gated on the AI feature)
• run_routine_procedure with parameter binding
• run_designer_ddl with implicit read_only gate and preview-DDL return
• run_compare_sync returning per-statement success/failure
• cancel_query, execute_query_stream, explain_query, format_sql, get_query_history
• ai_generate_sql, ai_explain_query, ai_optimize_query
• import_data, preview_import, export_data
• get_users, get_server_status, table_maintenance, get_foreign_keys, refresh_schema

Proposed fix

Scope L. Multi-PR refactor. Track via a single design note in docs/design/ARCHITECTURE.md §5 with sub-issues per command (most are already filed via per-feature audits; this is the unifying meta-issue that says "ARCHITECTURE §5 and invoke_handler![] must reach parity within one release"). Pair with #277 (read_only enforcement) and #281/#284 (cancellation/streaming) for the priority sub-fixes.

Acceptance

grep -E "async fn " docs/design/ARCHITECTURE.md §5 declared count equals grep -c "tauri::command" src-tauri/src/commands/*.rs registered count within one release. Read-only enforcement moves into the executor and is independent of the caller (resolves #277). Per-feature audit issues #284, #281, #412, #363, #429, #310 each close.

Needs human verify

Yes (compile + runtime).

Labels: audit, area/cross-cutting, severity/p1, kind/arch