chore(api): deprecate raw transaction trio; migrate MCP async paths to RAII (#69)

[StefanSteiner]

Resolves #69.

Consolidates the public transaction API around the RAII Transaction<'conn> / AsyncTransaction<'conn> guards. The raw &self begin_transaction / commit / rollback methods on Connection and AsyncConnection are now #[doc(hidden)] #[deprecated] — they remain callable for now but are hidden from generated rustdoc and emit a compiler warning at every call site. The MCP server's async pool-path ingest functions are migrated to use the RAII guard, demonstrating the recommended pattern in 4 production code sites.

Soft-deprecation, not removal. The original issue proposed full removal of the trio. After spike + investigation, the workspace's hyperdb-mcp::Engine::execute_in_transaction helper takes &self and so cannot use the RAII guard without restructuring Engine's lock model. Rather than block #69 on that structural change, this PR ships the public-API safety win (deprecation + hide) and the four mechanical MCP migrations now, and tracks the engine-level migration as a follow-up. See .issue-body-mcp-engine-raii-migration.md for the followup scope and two implementation paths.

Lands as chore: to defer release-please from cutting an early version; the v0.3.0 bump happens after the rest of the bundle merges. See MIGRATING-0.3.md for the consolidated migration guide.

What changed

hyperdb-api

• Added pub(crate) canonical implementations:
  • Connection::{begin_transaction_raw, commit_raw, rollback_raw} (sync)
  • AsyncConnection::{begin_transaction_raw, commit_raw, rollback_raw} (async)
• The original pub methods became thin wrappers calling the _raw family, marked #[doc(hidden)] #[deprecated(note = "Use ...transaction() for an RAII guard. ...")].
• The RAII guards (Transaction, AsyncTransaction) switched their internal calls to the _raw family — no #[allow(deprecated)] annotation needed. They model the recommended pattern from inside the crate.

hyperdb-mcp

Four async pool-path ingest functions migrated to the RAII guard:

• ingest_csv_file_async
• ingest_json_async
• ingest_parquet_file_async
• ingest_arrow_ipc_file_async

Each rewrote the conn.begin_transaction().await? ... conn.commit().await? pattern into:

let txn = conn.transaction().await.map_err(McpError::from)?;
let inner: Result<u64, McpError> = async {
    /* work via txn.connection() and txn.execute_command(...) */
}.await;
let row_count = match inner {
    Ok(n) => { txn.commit().await.map_err(McpError::from)?; n }
    Err(e) => { let _ = txn.rollback().await; return Err(e); }
};

The function signatures changed from &AsyncConnection to &mut AsyncConnection (the borrow-checker truth: a transaction needs exclusive use of the session). ~7 caller sites in server.rs, watcher.rs, and tests/ingest_arrow_tests.rs updated to bind let mut conn = pool.get().await? and pass &mut conn.

Engine::execute_in_transaction retained the deprecated raw methods under #[allow(deprecated, reason = "...")]. It cannot migrate without reshaping the Engine lock model — tracked as the follow-up issue.

Tests / examples / docs

• hyperdb-api/tests/transaction_tests.rs and wire_desync_tests.rs exercise the deprecated raw API on purpose to lock in its behavior. File-level #![allow(deprecated, reason = "...")] documents the intent.
• hyperdb-api/examples/additional_examples/transactions.rs keeps both the raw and RAII demonstrations side-by-side for educational purposes; same file-level allow.
• docs/TRANSACTIONS.md reorganized: RAII is the only documented path, with a "Deprecated raw methods" section at the bottom carrying the migration recipe.
• MIGRATING-0.3.md adds a #69 section with sync + async migration recipes and the pooled-connection caveat.

Verification

• cargo build --workspace --all-targets — clean
• cargo clippy --workspace --all-targets -- -D warnings — clean
• cargo test --workspace — all targets pass (300+ tests, 0 failures, including doctests)
• cargo fmt --check — clean

Process notes

• Plan-driven 5-phase workflow with parallel adversarial review at the plan and pre-PR checkpoints. Both reviewers caught real defects on the integrated diff:
  • Stale rustdoc on create_table_async recommending the deprecated pattern (fixed)
  • Misleading "wire-state quirk" comment on the post-commit COUNT(*) call (fixed)
  • The follow-up issue scope was a one-liner; expanded to two structural paths + acceptance criteria in .issue-body-mcp-engine-raii-migration.md (added)

Related

• MIGRATING-0.3.md — consolidated migration guide for the v0.3.0 bundle
• .issue-body-mcp-engine-raii-migration.md — followup scope for the remaining Engine::execute_in_transaction migration
• Bundle: Flatten Error type to canonical M-ERRORS shape (drop Client wrapper, Box<dyn> source, Option<ErrorKind>) #70 (PR chore(api): flatten Error enum and add ergonomic constructors workspace-wide (#70) #71, merged), this PR (Remove the &self begin_transaction/commit/rollback trio (RAII Transaction is the only safe path) #69), upcoming combined PR for Add #[derive(FromRow)] and named-column access for cleaner struct mapping #61+FromRow redesign (breaking): typed RowAccessor, structured errors, enforced NULL semantics #62 (FromRow modernization), then v0.3.0 cleanup follow-ups before the rollup feat!: commit cuts v0.3.0

Test plan

• CI green on this branch
• Smoke-test cargo run --example transactions and cargo run --example async_parity_smoke against a local hyperd
• Cross-link review of MIGRATING-0.3.md recipes against the actual public API