docs: reconcile v9 release notes and upgrade guide with shipped features

release_notes/v9.0.0.md and UPGRADE_V8_TO_V9.md only covered the initial
async-queries PR; add the mTLS, Search, RuntimeStatus,
ListActiveQueries/CancelActiveQuery, and Nsql additions and the ADBC
re-auth fix that landed on trunk since, and fix the changelog compare
link to the correct v8.0.1 predecessor tag.

Author: krinart

UPGRADE_V8_TO_V9.md

@@ -9,6 +9,8 @@ gospice v9 is a new major version. Unlike v8 (which was backward compatible with
 3. **Minimum Go version is now 1.25** (was 1.24).
 4. **Apache Arrow upgraded to v18.6.0** and **ADBC to v1.11.0**, matching the Spice.ai runtime's DataFusion 54.
 
+None of the other v9 additions below require code changes to adopt — they are new, opt-in APIs.
+
 ## 1. Update the import path
 
 ```bash
@@ -105,11 +107,23 @@ gospice v9 upgrades its Apache Arrow dependencies to match the Spice.ai runtime
 
 Running `go mod tidy` after updating the import path will pull these in automatically.
 
+## 5. New in v9 (no migration required)
+
+These are new, additive APIs — nothing to change if you don't use them:
+
+- **Mutual TLS.** `WithTLSClientCertificate(certFile, keyFile)` and `WithTLSRootCertificate(caFile)` client options for presenting a client certificate and/or verifying the server against a custom CA.
+- **`Search`** against the runtime's `/v1/search` endpoint for embedding-based document search.
+- **`RuntimeStatus`** for per-component (`http`, `flight`, `metrics`, `opentelemetry`) status, complementing the existing `IsSpiceReady`.
+- **`ListActiveQueries` / `CancelActiveQuery`** for inspecting and cancelling synchronous queries running on the runtime. See the README for the scope and runtime-version caveats.
+- **`Nsql` / `NsqlGenerateSQL`** for natural-language querying against the runtime's `/v1/nsql` endpoint.
+
+Also, ADBC connections (`SqlWithParams`) now automatically re-authenticate and retry once when the server invalidates the session, instead of failing permanently — no code changes needed to benefit from this.
+
 ## Unchanged APIs
 
 Everything else is source-compatible with v8, including:
 
 - `Sql()` and `SqlWithParams()`
 - `IsSpiceHealthy()` and `IsSpiceReady()`
-- Client initialization (`NewSpiceClient`, `Init`, `WithApiKey`, `WithSpiceCloudAddress`, `WithFlightAddress`, `WithHttpAddress`, mTLS options)
+- Client initialization (`NewSpiceClient`, `Init`, `WithApiKey`, `WithSpiceCloudAddress`, `WithFlightAddress`, `WithHttpAddress`)
 - `RefreshDataset()` and the typed parameter constructors

docs/release_notes/v9.0.0.md

@@ -1,6 +1,6 @@
 # Announcing gospice v9.0.0 - Async Queries & DataFusion 54 🚀
 
-gospice v9.0.0 introduces **asynchronous queries** and upgrades the Apache Arrow stack to match the Spice.ai runtime built on DataFusion 54. This is a major release with breaking changes.
+gospice v9.0.0 introduces **asynchronous queries** and upgrades the Apache Arrow stack to match the Spice.ai runtime built on DataFusion 54. It also adds mutual TLS, semantic search, per-component runtime status, active-query management, and natural-language querying. This is a major release with breaking changes.
 
 ## 🎯 Major Features
 
@@ -36,6 +36,29 @@ gospice v9 upgrades to the Apache Arrow releases that match the Spice.ai runtime
 - **Apache Arrow Go** `v18.4.1` → `v18.6.0`
 - **ADBC Go driver** `v1.9.0` → `v1.11.0`
 
+### Mutual TLS (mTLS)
+
+`Init` accepts two new options for securing the connection to the runtime:
+
+- `WithTLSClientCertificate(certFile, keyFile)` presents a PEM-encoded client certificate during the TLS handshake for mTLS authentication.
+- `WithTLSRootCertificate(caFile)` verifies the server against a custom CA certificate instead of (or in addition to) the system certificate store.
+
+### Search
+
+`Search` finds documents similar to a piece of text via the runtime's `/v1/search` endpoint, against datasets with an embedding column and a loaded embedding model. It supports restricting to specific datasets, a SQL `Where` filter, additional returned columns, and a hybrid lexical+vector ranking via `Keywords`.
+
+### Runtime Status
+
+`RuntimeStatus` reports per-component status (`http`, `flight`, `metrics`, `opentelemetry`) via `/v1/status`, distinguishing a runtime that is still initializing from one whose Flight endpoint is failing — unlike `IsSpiceReady`, which reports a single boolean for the whole runtime.
+
+### Listing and Cancelling Running Queries
+
+`ListActiveQueries` reports the synchronous queries running in the caller's scope (from `Sql`, `SqlWithParams`, FlightSQL, NSQL, and `Search`), and `CancelActiveQuery` stops one by ID — the runtime never hands a query's ID back to the client that submitted it, so these are meant to be used together. See the README for the scope and runtime-version caveats that apply.
+
+### Text-to-SQL (NSQL)
+
+`Nsql` answers a natural-language question by having the runtime's configured LLM generate SQL and run it, returning both the rows and the generated query. `NsqlGenerateSQL` generates the SQL without running it, so it can be inspected, edited, or run through `Query`/`Sql` for Arrow-typed results. Both call the runtime's `/v1/nsql` endpoint and require an LLM model configured in the Spicepod.
+
 ## 📦 What's Changed
 
 ### Breaking Changes
@@ -47,6 +70,15 @@ gospice v9 upgrades to the Apache Arrow releases that match the Spice.ai runtime
 
 - `AsyncQuery` handle type with `ID`, `Status`, `Wait`, `Results`, and `Cancel`.
 - `QueryStatus` type and constants.
+- `WithTLSClientCertificate` and `WithTLSRootCertificate` client options for mTLS.
+- `Search` and `SearchRequest`/`SearchResponse`/`SearchMatch`.
+- `RuntimeStatus` and `ConnectionDetails`/`ComponentStatus`.
+- `ListActiveQueries` and `CancelActiveQuery`, and the `ActiveQuery` type.
+- `Nsql` and `NsqlGenerateSQL`, and the `NsqlRequest`/`NsqlResponse`/`NsqlSchema`/`NsqlField` types.
+
+### Fixed
+
+- **ADBC connections re-authenticate instead of failing permanently.** `SqlWithParams` previously treated an `Unauthenticated`/`Unauthorized` error from an expired server-side session as permanent, leaving the connection unusable until the process restarted. It now re-opens the ADBC connection and retries the query once.
 
 ### Changed
 
@@ -56,7 +88,7 @@ gospice v9 upgrades to the Apache Arrow releases that match the Spice.ai runtime
 
 ### Unchanged
 
-- `Sql()` / `SqlWithParams()`, `IsSpiceHealthy()` / `IsSpiceReady()`, client initialization, mTLS support, `RefreshDataset()`, and the typed parameter constructors are all source-compatible with v8.
+- `Sql()` / `SqlWithParams()`, `IsSpiceHealthy()` / `IsSpiceReady()`, client initialization, `RefreshDataset()`, and the typed parameter constructors are all source-compatible with v8.
 
 ## 🔧 Migration Guide
 
@@ -81,4 +113,4 @@ import "github.com/spiceai/gospice/v9"
 - 🐛 Issues: [github.com/spiceai/gospice/issues](https://github.com/spiceai/gospice/issues)
 - 💬 Discord: [spice.ai/discord](https://spice.ai/discord)
 
-**Full Changelog**: <https://github.com/spiceai/gospice/compare/v8.0.0...v9.0.0>
+**Full Changelog**: <https://github.com/spiceai/gospice/compare/v8.0.1...v9.0.0>