chore(api): v0.3.0 follow-ups (A: typed I/O sources, B: InvalidOperation, C: structured SQLSTATE)

[StefanSteiner]

Summary

The four #70 follow-ups for the v0.3.0 bundle. 3 of 4 land here; D defers to v0.3.x as #75.

• A — Typed I/O sources in process.rs. 12 io::Error sites in HyperProcess startup/shutdown move from Error::internal(format!("...: {e}")) to Error::connection_with_io(message, e), preserving the typed std::io::Error so callers can introspect via std::error::Error::source().
• B — Error::InvalidOperation variant. Separates caller-API misuse from library invariant violations. 5 ArrowInserter state-machine errors (mode mixing, schema-already-sent) move from Error::Internal to Error::InvalidOperation. Error::Internal rustdoc clarified to point at InvalidOperation for caller misuse.
• C — Structured SQLSTATE on Cancelled / Closed / Connection. Reverses the post-Flatten Error type to canonical M-ERRORS shape (drop Client wrapper, Box<dyn> source, Option<ErrorKind>) #70 caveat. SQLSTATE codes that arrive via cancellation (57014), connection-class (08*), or close-class (57P0*) wire errors are now exposed via the variant's sqlstate field and Error::sqlstate() returns them. Breaking: Error::Cancelled and Error::Closed change from tuple to struct variants. Error::Connection gains a sqlstate field.
• D (deferred) — Flatten internal client::Error. 51 producers + 15 kinds, larger than originally scoped, internal-only (zero external consumers), no user-facing benefit. Filed as #75 for v0.3.x.

Bundle policy: chore: prefix to defer release-please version bump until the v0.3.0 rollup feat: commit. Each follow-up is breaking on its own; landing under the bundle umbrella.

Commits

1. 13f6942 — docs typo fix (feat!: → feat:) in MIGRATING-0.3.md rollup note.
2. 9dde324 — Follow-up A. 12 io::Error sites migrated; 6 non-IO sites left as Error::internal (timeout, descriptor parse, state assertions).
3. 33f73e4 — Follow-up B. New variant + constructor; 5 inserter state-machine sites migrated; mutex-poisoned sites correctly stay Internal (upstream panic, not caller misuse).
4. 666aa4f — Follow-up C. Variant restructuring + 3 new *_with_sqlstate constructors; broadened Error::sqlstate(); updated From<client::Error> mapping; one MCP match site updated for the tuple→struct transition.

Migration

Highlights from MIGRATING-0.3.md:

// Follow-up B — caller-misuse vs invariant
match err {
    Error::InvalidOperation(_) => /* user-API misuse, caller bug */,
    Error::Internal { .. } => /* library invariant violation */,
    other => return Err(other),
}

// Follow-up C — destructure for SQLSTATE, or use the helper
match err {
    Error::Cancelled { message, sqlstate: Some(code), .. } if code == "57014" => { /* user cancel */ }
    Error::Closed { sqlstate: Some(code), .. } if code == "57P01" => { /* admin shutdown */ }
    other => return Err(other),
}

if err.sqlstate() == Some("08006") { /* connection failure */ }

Verification

• cargo build --workspace --all-targets ✅
• cargo clippy --workspace --all-targets -- -D warnings ✅
• cargo test --workspace (full, including doctests) ✅ — 81 test groups pass
• cargo fmt --check ✅
• cargo doc --workspace --no-deps ✅ — 6 warnings (= post-Flatten Error type to canonical M-ERRORS shape (drop Client wrapper, Box<dyn> source, Option<ErrorKind>) #70 baseline)
• cargo run --example async_parity_smoke ✅ — 10 stages pass

Why Follow-up D defers

Scope grew on second look. Original plan estimated "6 producers, mechanical." Actual workspace state: 51 producer call sites in hyperdb-api-core/src/client/{client,async_client,connection,grpc/*,tls}.rs, with 15 ErrorKind variants (3 more than #70's public type — InvalidData, InvalidInput, UnexpectedEof).

No user-facing benefit. client::Error is internal — not re-exported from hyperdb-api, zero external consumers (verified via grep). The benefit of flattening it is purely codebase-internal hygiene.

v0.3.0 has all user-facing improvements without it. Shipping the bundle on time matters more than internal cleanup that downstream callers can't observe.

Filed as #75 for v0.3.x. Approach mirrors #70's pattern.

Test plan

• All workspace gates green on macOS aarch64
• Unit tests for Error::InvalidOperation constructor + Error::sqlstate() broadened behavior
• async_parity_smoke end-to-end against local hyperd
• Adversarial review (line-level + architectural reviewers in parallel) — both clean
• Linux CI (will run on push)

This closes the v0.3.0 follow-up work. Next step in the bundle: the rollup feat: commit with a BREAKING CHANGE: footer aggregating #70, #69, #61, #62, and follow-ups A/B/C.