chore(api): modernize FromRow with #[derive] + RowAccessor (#61, #62)

[StefanSteiner]

Summary

Modernizes FromRow for the v0.3.0 bundle (closes #61, #62):

• Introduces RowAccessor<'a> — name-based column access with a per-query cached HashMap<&str, usize> lookup. Replaces the &Row parameter on FromRow::from_row (breaking).
• Adds #[derive(FromRow)] in a new workspace crate hyperdb-api-derive, re-exported from hyperdb-api (same pattern as serde / thiserror / tokio). Supports #[hyperdb(rename = "...")] for column-name overrides and #[hyperdb(index = N)] for positional access (useful with computed/unnamed columns like SELECT id, COUNT(*) FROM ... GROUP BY id).
• Adds Row::get_by_name<T>(name) for one-off named access outside fetch_*_as (linear scan; rustdoc steers hot paths to the derive).
• Deletes the four blanket tuple FromRow impls — define a struct with #[derive(FromRow)] instead.
• Migrates the three hand-written FromRow impls in tests/examples; documents migration in MIGRATING-0.3.md.

Bundle policy: chore: prefix to defer release-please version bump until the v0.3.0 rollup feat!: commit. PR is breaking — landed under the bundle umbrella.

Commits

1. e705aa5 — Foundation: RowAccessor, trait signature change, Row::get_by_name, fetch_*_as cache, hand-written impl migration, 8 unit tests.
2. 70356c4 — hyperdb-api-derive crate; #[derive(FromRow)] with #[hyperdb(rename = "...")]; integration tests (parity, NULL, rename, missing-column).
3. ac3166e — MIGRATING-0.3.md #61+#62 section.
4. 676a4c2 — Final-review fixes: RowAccessor::position returns structured Error::Column { kind: Null | TypeMismatch }; removes leak-vector RowAccessor::row(); clearer attribute error message.
5. 378c0a6 — Adds #[hyperdb(index = N)] and RowAccessor::position_opt. Mutually exclusive with rename. Integration test against a COUNT(*) query.
6. a50b97a — Derive crate README: 2×2 accessor cheat sheet, zero-based indexing note, type-system rules for the position / position_opt pair.

Why a separate hyperdb-api-derive crate

Rust requires #[proc_macro_derive] to live in a crate with proc-macro = true. hyperdb-api-core is not a proc-macro crate and cannot host the derive. Re-export from hyperdb-api means downstream callers do use hyperdb_api::FromRow; and never depend on hyperdb-api-derive directly — same ergonomic shape as serde / thiserror.

Performance

Ran cargo run --release --example benchmark_suite -- 200000 against this branch and against main (origin/main = 5c7e78b). N=1 at 200K rows; deltas are within typical run-to-run noise on this M3 Max. No regression observed.

Workload	Variant	main rows/s	PR rows/s
insert.bulk	Inserter (HyperBinary)	3.37 M	4.68 M
insert.bulk	ChunkSender × 4	3.63 M	5.10 M
insert.bulk	AsyncArrowInserter	5.24 M	6.59 M
query.full_scan	sync single	9.79 M	7.24 M
query.full_scan	async single	8.85 M	11.80 M
query.filtered	sync single	3.81 M	4.56 M
query.aggregation	sync single	1.43 K	1.94 K

The fetch_*_as cached-index path is hit by the FromRow tests rather than the bulk-insert/query benchmarks — the lookup is O(N) once per query plus O(1) per field per row, strictly better than the previous "no cache, hand-coded positions" pattern.

Migration

MIGRATING-0.3.md covers the recipes; the short version:

// Before
impl FromRow for User {
    fn from_row(row: &Row) -> Result<Self> { /* ... */ }
}

// After
impl FromRow for User {
    fn from_row(row: RowAccessor<'_>) -> Result<Self> {
        Ok(User { id: row.get("id")?, name: row.get_opt("name")?.unwrap_or_default() })
    }
}

// Or just derive it
#[derive(FromRow)]
struct User { id: i32, name: Option<String> }

Tuple FromRow impls are gone; define a struct.

Verification

• cargo build --workspace --all-targets ✅
• cargo clippy --workspace --all-targets -- -D warnings ✅
• cargo test --workspace (full, including doctests) ✅
• 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)
• grep -rn 'fn from_row(row: &Row)' --include='*.rs' . → zero hits
• cargo run --example async_parity_smoke against local hyperd ✅

Test plan

• Workspace build/clippy/test/fmt/doc all green on macOS aarch64
• RowAccessor unit tests cover Missing, Null, TypeMismatch, position-OOB, position-Null
• Derive integration tests cover parity-with-handwritten, NULL → None on Option<T>, #[hyperdb(rename)], #[hyperdb(index)] (against SELECT id, COUNT(*) FROM ... GROUP BY id), missing column → Error::Column { kind: Missing }
• async_parity_smoke example exercises the new fetch_*_as cached-index path end-to-end
• Linux CI (will run on push)

Closes #61
Closes #62