feat(python)!: expose typed query errors and request metadata (#4832)

Remote SQL failures currently become generic runtime errors, and HTTP
table lookup can discard server error metadata. Preserve transport
status, current request ID, SQL job ID and worker request ID across Rust
and Python. Select typed column, table, reference and schema exceptions
only when an explicit server code matches the transport status.

Remote `HttpError` and `RuntimeError` handlers remain compatible. Failed
SQL jobs retain `JobFailedError` with a typed SQL cause when available.
Missing metadata stays absent; message text never determines the
exception class. Local missing-column errors retain their type and
qualified-field suggestions, and `JobFailure.source` documents
structured remote Flight SQL failures.

This branch integrates main at `a9ad4997`, including its released Lance
15.0.0-beta.9 dependency update and remote optimize support. The only
textual conflict was two independent additions to `test_remote_db.py`;
both test groups and all original assertions are retained. The feature
has no dependency or lockfile delta against current main.

SDK runtime validation on `03ee633a` (runtime source unchanged in
`f3f2d0b8`), macOS ARM64, pinned Rust 1.97.0 and the frozen uv Python
3.14 environment:

- Rebuilt the native extension from the integrated source. All 22
targeted Python tests passed: native local errors, HTTP/Flight metadata,
legacy sync/async table-not-found behavior, and the three main
remote-optimize regressions.
- All 52 Rust SQL, metadata/source and nested-field tests passed,
including the new main optimize cases.
- Root and Python-binding Rust Clippy with `-D warnings`, Rust
formatting, Python package Ruff and conflict-file formatting passed.
- Repository-wide Ruff reports 59 existing documentation findings, and
its format check identifies six documentation files. Every affected file
is byte-identical to current main; these checks are not reported as
passing.
- Direct integration review and AST comparison confirm both conflicting
test groups were preserved. Earlier exception-constructor/pickling
evidence remains applicable to the unchanged Python error modules.

The unlocked build exhausted disk again on a runner with the same label
but only 9.4 GiB free on a 72 GiB root filesystem. Keep the existing
runner and dependency caches, serialize Cargo compilation, and remove
only completed test/bench executables reported by Cargo. This job never
runs those binaries; normal binaries, libraries and build-script outputs
remain available. Fresh resolution, the ci profile, all features, and
test/bench compilation and linking are retained.

Three probes using Cargo and target-path validation pass with `-D
warnings`: all fixture targets link while ordinary outputs remain
usable; an undefined symbol still produces Cargo exit 101 and its linker
diagnostic; files outside the target directory are never removed. The
[current-head build-no-lock
job](https://github.com/lancedb/lancedb/actions/runs/41911613851/job/126860364065)
passed on `f3f2d0b8`: all compilation/linking completed, 20 completed
test executables were removed, and `target` retained about 7.3 GiB. This
successful run had a 145 GiB root with about 78 GiB free afterward; it
was not an identical rerun of the failed 72 GiB image. The driver tests
also passed in this job. All previous-head jobs ended naturally before
the push; new-head CI and review gates still apply.

Typed remote input exceptions require the server metadata contract.
Older servers retain generic transport errors and existing missing-table
compatibility. The optimize tests use mock servers and do not establish
downstream server acceptance.

BREAKING CHANGE: Rust callers with exhaustive matches on
`lancedb::Error` must handle the new `FieldNotFound` and `Sql` variants.
Local `Error::ColumnNotFound` failures now raise
`lancedb.exceptions.ColumnNotFoundError`, a `ValueError` subclass.
Python callers that previously caught only `RuntimeError` for this local
failure must catch `ColumnNotFoundError` or `ValueError`.

docs/src/python/python.md

@@ -833,12 +833,61 @@ except HttpError as error:
     print("request failed:", error.request_id, error.status_code)
 ```
 
-Secret and function lifecycle APIs currently use Flight SQL and may still raise
-`RuntimeError`. The typed subclasses cover HTTP failures, including dependency
-errors during column refresh.
+SQL response failures raise `SqlError`, retaining the numeric `grpc_code` and
+`request_id`. Servers that report a recognized `x-lancedb-error-code` select a
+specific input-error subclass. HTTP failures use the corresponding `HttpError`
+subclass. Missing metadata stays absent; diagnostic text is never used to guess
+the error type. An Internal or Unavailable response remains a server failure,
+even if its message or metadata resembles an input error.
+
+For errors that can arrive over either transport, catch the shared input type:
+
+```python
+from lancedb.exceptions import ColumnNotFoundError, SchemaMismatchError
+from lancedb.remote.errors import HttpError, SqlError
+
+try:
+    db.execute_query("SELECT missing FROM events").read_all()
+except (ColumnNotFoundError, SchemaMismatchError) as error:
+    print(error.request_id, error.job_id, error.job_request_id)
+except (HttpError, SqlError) as error:
+    print(error.request_id)
+```
+
+`ReferenceNotFoundError` identifies a missing branch or table reference. Table
+errors are `TableNotFoundError` for HTTP and `SqlTableNotFoundError` for SQL;
+both remain compatible with `lance_namespace.errors.TableNotFoundError`.
+
+A background SQL job still raises `JobFailedError`. Its `__cause__` is the typed
+`SqlError` when available, and both carry the current `request_id` and original
+worker `job_request_id`. The outer job ID can differ from `sql_job_id`. These
+fields are `None` when the server does not report them. Older servers produce
+generic HTTP/SQL exceptions with their transport status and current request ID.
 
 ::: lancedb.remote.errors.HttpError
 
+::: lancedb.remote.errors.ColumnNotFoundError
+
+::: lancedb.remote.errors.ReferenceNotFoundError
+
+::: lancedb.remote.errors.SchemaMismatchError
+
+::: lancedb.remote.errors.SqlError
+
+::: lancedb.remote.errors.SqlColumnNotFoundError
+
+::: lancedb.remote.errors.SqlTableNotFoundError
+
+::: lancedb.remote.errors.SqlReferenceNotFoundError
+
+::: lancedb.remote.errors.SqlSchemaMismatchError
+
+::: lancedb.exceptions.ColumnNotFoundError
+
+::: lancedb.exceptions.ReferenceNotFoundError
+
+::: lancedb.exceptions.SchemaMismatchError
+
 ::: lancedb.remote.errors.TableNotFoundError
 
 ::: lancedb.remote.errors.SecretNotFoundError