chore(mcp): atomic multi-statement execute via array sql parameter

[StefanSteiner]

Summary

The MCP execute tool's sql parameter changes from String to Vec<String>. Multi-element arrays run inside a Hyper transaction so all statements commit together or all roll back. The canonical use case is the Hyper-style upsert (no ON CONFLICT in Hyper):

execute({ "sql": [
  "UPDATE settings SET value = 'dark' WHERE key = 'theme'",
  "INSERT INTO settings (key, value) SELECT 'theme', 'dark'
     WHERE NOT EXISTS (SELECT 1 FROM settings WHERE key = 'theme')"
]})

Single-element arrays (["UPDATE …"]) skip BEGIN/COMMIT entirely and keep the existing auto-commit behavior. The breaking shape change is intentional — the only consumers are LLM clients and an array is the natural shape for batched SQL.

Validation rules (enforced before any SQL hits hyperd)

1. Non-empty array; no empty / whitespace-only / comment-only elements.
2. No element may be read-only — use the query tool for SELECT/WITH/EXPLAIN.
3. Explicit BEGIN / COMMIT / ROLLBACK / SAVEPOINT in array elements are rejected — the wrapper manages the transaction, and a user-issued COMMIT mid-batch would silently break atomicity.
4. DDL+DML cannot be mixed in one batch (Hyper aborts mixed transactions with 0A000).
5. Multi-element all-DDL batches are rejected — Hyper auto-commits CREATE/DROP/ALTER even inside a transaction, so the "atomic" promise can't be honored.

Multi-statement input within a single array element (e.g. "UPDATE a; UPDATE b") is not caught client-side. The handler defers to Hyper's own wire-protocol error (SQLSTATE 0A000 / "Multi-part queries"), and the existing error-mapping rewrites that into "Hyper only accepts one SQL statement per call. Split your query into separate execute/query calls" before it surfaces to the LLM. This keeps validation focused on correctness rules rather than reimplementing a SQL lexer.

Response shape

Uniform across single- and multi-statement batches:

{
  "statements": 2,
  "affected_rows": 1,
  "per_statement": [
    { "sql": "UPDATE settings …", "affected_rows": 0, "elapsed_ms": 1.2 },
    { "sql": "INSERT INTO settings …", "affected_rows": 1, "elapsed_ms": 0.8 }
  ],
  "stats": { "operation": "transaction", "elapsed_ms": 4.7 }
}

Singletons report operation: "command" and statements: 1.

Documentation

Both READMEs updated:

• hyperdb-mcp/src/readme.rs (the get_readme tool's payload) — tool index, no-ON CONFLICT note with the array-form pattern, response-shape spec, atomic-upsert example.
• hyperdb-mcp/README.md — rewrote the execute tool block, added Upserts and Transactions subsections that reference docs/TRANSACTIONS.md for the underlying API semantics.

Tests

6 commits (feature → docs → engine integration tests → fix transaction-control rejection → reviewer follow-ups → drop client-side multi-statement lexer). Test coverage:

• 3 helper unit tests in engine.rs covering classify_statement (DDL/DML/read-only/transaction-control/other classification, comment-stripping).
• 10 validator unit tests in server.rs covering every rejection path plus happy paths (empty array, whitespace-only, read-only element, transaction-control in batch, transaction-control singleton, DDL+DML mix, multi-DDL, single-DDL, multi-DML, allows trailing semicolon).
• 3 engine-level integration tests in transaction_tests.rs against real hyperd: upsert insert path, upsert update path, multi-table rollback on second-statement failure.
• 4 MCP-handler-level integration tests in end_to_end_mcp_tests.rs going through full rmcp dispatch (validation, search-path guard, transaction wrapper, response envelope): atomic-upsert commit, mid-batch rollback with per-statement-index naming, DDL/DML rejection, singleton auto-commit.
• Pre-existing execute calls in end_to_end_mcp_tests.rs updated to the new array shape.

Test plan

• CI green on the PR (workspace lint/build/test).
• Manual smoke through Claude Code / Cursor against a freshly-built hyperdb-mcp:
  • Single-element happy path: execute({"sql":["CREATE TABLE t (k TEXT, v TEXT)"]}).
  • Atomic upsert: the canonical UPDATE+INSERT-WHERE-NOT-EXISTS pair, twice (insert path on first call, update path on second).
  • Forced rollback: a two-element batch where the second statement violates a constraint; verify the first row is not present afterward.
  • DDL/DML mix rejection surfaces with the SQLSTATE-0A000 reference in the suggestion.
  • BEGIN-only singleton is rejected with the "tool manages the transaction" suggestion.
  • Inner-multi-statement element (e.g. ["UPDATE a; UPDATE b"]) surfaces Hyper's "Multi-part queries" error with the existing error-mapping suggestion to split into separate elements.