refactor(mcp)!: drive Engine transactions with the RAII guard, and flatten client::Error

[StefanSteiner]

Closes #72
Closes #75

Two related refactors: hyperdb-mcp's Engine now drives transactions with the RAII Transaction guard, and hyperdb_api_core::client::Error is flattened to one variant per failure mode.

Both commits carry !. main already pins the next release to 1.0.0-rc.2 with a Release-As: footer, so the markers do not push the workspace to 2.0.0.

#72 — RAII transactions in Engine

The issue's premise was stale. It described the code as calling the deprecated Connection::begin_transaction / commit / rollback wrappers. Those were deleted in 1.0.0, so Engine was already on the sanctioned, undeprecated *_unguarded API rather than on deprecated calls. The real work is adopting the guard.

Engine::execute_in_transaction now takes &mut self, holds a hyperdb_api::Transaction, and hands the closure an EngineTransaction view instead of &Engine. That is the substantive win: transactional code can no longer reach the raw connection and issue statements around the transaction it is supposed to be inside. EngineTransaction exposes only what the call sites actually use — execute_command, create_table_in, and connection() for ArrowInserter.

Scope of the change:

• Seven closure call sites migrated to the EngineTransaction view.
• A &mut Engine signature cascade through seven ingest entry points, merge_via_temp_table, and HyperMcpServer::with_engine. This costs nothing: the engine already lives behind an exclusive Arc<Mutex<Option<Engine>>>, so no caller was ever sharing it.
• A new Engine::with_search_path(alias, f) was needed. The previous ScopedSearchPath borrows &Engine for its whole lifetime and runs SQL on drop, which cannot coexist with the transaction's exclusive borrow of the same connection. The closure form sequences set/restore around f rather than holding a borrow across it, and restores on the Ok, Err, and panic paths. scoped_search_path is unchanged and still preferred where &Engine suffices.
• create_table_in's validation and identifier quoting move into a shared create_table_statements builder so the &Engine and transaction-scoped paths cannot drift.

Worth flagging: the design the issue itself sketched would have deadlocked. It holds the connection mutex while calling f(self), and the closure's execute_command then re-locks a non-reentrant std::sync::Mutex.

Removing the old catch_unwind is behaviour-preserving. The guard's Drop performs the same best-effort rollback and the unwind continues untouched. Transaction::drop now also logs that rollback (warn! on failure, debug! on success), restoring the observability the catch_unwind provided on the panic path.

An asymmetry worth stating plainly

Sync Transaction::drop issues a best-effort rollback when the transaction was not committed. Async AsyncTransaction::drop cannot roll back at all — Rust has no async drop. It only emits a warning, and the transaction is left open until the next command on that connection. The guard is therefore not an equivalent safety net on the async side.

Six unguarded call sites deliberately remain

KvStore::{pop, set_batch, set_batch_if_absent} and the three AsyncKvStore equivalents still call the *_unguarded trio. They are not oversights, and MIGRATING-0.3.md and docs/TRANSACTIONS.md now document them as holdouts.

KvStore<'conn> holds a shared &'conn Connection, while Connection::transaction() takes &mut self. Adopting the guard would mean threading &mut out through the public Connection::kv_store() — which breaks published API and would prevent holding two stores on one connection. This is exactly the case hyperdb-api/CHANGELOG.md already documents: the *_unguarded methods exist precisely for "a helper that holds &self". The async three have the further problem above, which no guard can fix.

#75 — flatten client::Error

hyperdb_api_core::client::Error becomes a flat thiserror enum with one variant per failure mode, mirroring what #70 did for the public error type. It was a struct carrying kind: ErrorKind plus a Box<dyn StdError + Send + Sync> cause channel, which forced a two-level match and type-erased the cause.

#[non_exhaustive] was deliberately not used. The crate documents the type as forever-internal with no semver promise, so forward-compatibility there would buy nothing, and it would cost the compile-time exhaustiveness check on the one match that must give every variant a public meaning. A variant added upstream should break that build rather than silently landing in Error::Internal.

The Box<dyn> cause channel is dropped. with_cause had zero call sites, so nothing that was ever populated is lost — and removing it fixed a real display bug: Error::io stored the same text as both message and cause, so an I/O failure rendered as "refused: refused".

Behaviour changes to call out for consumers

• The Display text for I/O-origin connection errors changes: "refused: refused" becomes "refused". This does reach the public hyperdb_api::Error, so anything string-matching on the message will notice.
• gRPC now folds detail into the message for the non-Query variants, and drops hint/sqlstate on those four. This reaches nobody today, since the public mapping already discarded them there.

From adversarial review

Three corrections that came out of review rather than the original work:

• Two doc claims introduced by this change were false. They asserted that no workspace code outside tests and examples calls the unguarded methods, while pointing readers away from the six holdouts above. Corrected.
• hyperdb-mcp/DEVELOPMENT.md overstated the guard. A panic still poisons with_engine's std::sync::Mutex; ensure_engine then returns Lock poisoned for every later tool call, and nothing calls clear_poison(), so the engine is wedged for the process lifetime regardless. That is pre-existing rather than a regression. The doc is now scoped to the SQL session, and mutex-poison recovery in ensure_engine is flagged as an open design question rather than changed silently — a reasonable follow-up, deliberately out of scope here.
• The missing_docs allow reason at hyperdb-mcp/src/lib.rs:6 claimed the crate is not published to crates.io. It is, at 1.0.0-rc.1. Corrected in passing.