feat: add generic search client traits and adapters (#994)

### Description

Introduce a family of search client traits with blanket implementations
and adapter utilities, replacing ad-hoc per-backend boilerplate with a
consistent, extensible design.

#### New traits (`stac::api`)

| Trait | Purpose | Required method |
| ----- | ------- | --------------- |
| `ItemsClient` | Single-page item search | `search` |
| `StreamItemsClient` | Stream items across all pages | `search_stream`
|
| `CollectionsClient` | Fetch all collections at once | `collections` |
| `PagedCollectionsClient` | Cursor-paginated collections
(future-proofing) | `collections_page` |
| `StreamCollectionsClient` | Stream all collections |
`collections_stream` |
| `ArrowItemsClient` *(geoarrow)* | Arrow record batch output |
`search_to_arrow` |
| `TransactionClient` | Write items and collections | `add_item`,
`add_collection` |

#### Blanket implementations

- `CollectionsClient + Clone + Sync → StreamCollectionsClient` — eagerly
fetches all collections and yields as a stream; no wrapper struct needed
- `ArrowItemsClient + Sync → ItemsClient + StreamItemsClient` *(geoarrow
feature)* — collects record batches synchronously and returns owned
items

#### Adapter utilities

- `PagedItemsStream\<T>` — wraps any `ItemsClient` to provide
`StreamItemsClient` via token/skip pagination (`ItemCollection::next`)
- `stream_pages_generic` — free function driving the items pagination
loop; used by `PagedItemsStream` and all server backends
- `stream_pages_collections_generic` — collections equivalent for
`PagedCollectionsClient` backends (ready for future paginated
`/collections` support)
- `RecordBatchReaderAdapter\<I>` *(geoarrow)* — bridges `Iterator<Item =
Result<RecordBatch, E>>` to `arrow_array::RecordBatchReader`

#### Backend implementations

All three server backends (memory, duckdb, pgstac) implement the full
trait family. `stac-duckdb` provides `HrefClient` (`ArrowItemsClient`)
and `SyncHrefClient` (`ItemsClient` + `CollectionsClient` +
`StreamItemsClient` via `Mutex`). `stac-io`'s `Client` implements
`StreamItemsClient` with HATEOAS link-following rather than token
pagination.

#### Design notes

- The `ItemsClient + Clone → StreamItemsClient` blanket cannot be added
because it would overlap with the `ArrowItemsClient` blanket under
Rust's coherence rules. Server backends use `stream_pages_generic`
directly in their explicit `StreamItemsClient` impls.
- `PagedCollectionsClient` has no blanket `StreamCollectionsClient` for
the same reason (would overlap with the `CollectionsClient` blanket).
Paginated backends call `stream_pages_collections_generic` in their own
impl.

### Related issues

- Groundwork for federated search / streaming backends

### Checklist

- [x] Unit tests
- [x] Documentation, including doctests
- [x] Pull request title follows [conventional
commits](https://www.conventionalcommits.org/en/v1.0.0/)
- [x] Pre-commit hooks pass (`prek run --all-files`)

---------

Co-authored-by: Pete Gadomski <pete.gadomski@gmail.com>

Author: bitner

.github/copilot-instructions.md

@@ -0,0 +1,82 @@
+# rustac - Agent Instructions
+
+## Workspace map
+
+- `crates/core` (`stac`): canonical types, API traits, shared logic.
+- `crates/io`: HTTP and object-store I/O.
+- `crates/duckdb`: DuckDB-backed querying.
+- `crates/server`: API server backends and wiring.
+- `crates/pgstac`: pgstac integration.
+- `crates/extensions`, `crates/validate`, `crates/wasm`, `crates/derive`, `crates/cli`: supporting crates.
+
+## Build and validation
+
+```sh
+cargo test
+cargo test -p stac
+prek run --all-files
+```
+
+DuckDB tests may require `DUCKDB_LIB_DIR`; alternatively use `--features duckdb-bundled` where supported.
+
+## High-level rules
+
+- Keep changes minimal and crate-local.
+- Keep default builds lightweight; gate optional capabilities behind features.
+- Preserve cross-crate consistency in naming, error shape, and docs style.
+
+## Error handling
+
+- One public error enum per crate in `src/error.rs` (typically `crate::Error`).
+- Use `thiserror`, `#[non_exhaustive]`, and `#[error(transparent)]`/`#[from]` for wrappers.
+- Document each error variant with a short doc comment.
+- Do not introduce parallel error enums when a new variant on crate `Error` is sufficient.
+
+## API and naming
+
+- Use names that describe behavior (for traits/functions), not implementation detail.
+- Avoid redundant suffixes/prefixes (`_generic`, duplicated context words).
+- Keep trait families coherent (`Items*`, `Collections*`, streaming variants).
+- Prefer explicit conversion adapters where coherence or ownership prevents a blanket impl.
+
+## Features and dependencies
+
+- Heavy or optional functionality must be feature-gated.
+- Keep Arrow/GeoArrow/GeoParquet dependencies scoped to relevant features.
+- Avoid widening default feature surfaces without strong need.
+- Prefer workspace dependency versions and existing crate patterns.
+
+## Async and memory behavior
+
+- Treat `Stream` as the async equivalent of `Iterator`.
+- Prefer streaming paths for large result sets.
+- If buffering is required, document the reason and bound memory when practical.
+- Be explicit about sync/async boundaries (for example, borrowed readers and blocking APIs).
+
+## Documentation
+
+- Library/API behavior belongs in Rust doc comments (`//!` and `///`).
+- Use module-level docs for design overviews and trait relationships.
+- Keep `docs/` focused on user-facing MkDocs content (CLI/history/site pages), not deep library internals.
+- Keep examples realistic and compile-aware (`no_run` when needed).
+
+## Testing
+
+- Favor real implementations for behavior tests.
+- Reserve mocks mainly for network/HTTP boundary simulation.
+- Unit tests: colocated in `#[cfg(test)] mod tests`.
+- Integration tests: crate `tests/` directories.
+- Use `#[tokio::test]` for async code paths.
+
+## Code style
+
+- Remove stray/placeholder comments and dead code.
+- Keep function docs and type docs short, factual, and behavior-focused.
+- Match existing formatting and module organization.
+
+## PR and git hygiene
+
+- Use conventional commit style for PR titles.
+- Run `prek run --all-files` before finalizing.
+- Keep history clean; squash fixups when requested.
+- Include tests and docs updates for behavior changes.

.gitignore

@@ -9,3 +9,4 @@ node_modules/
 package-lock.json
 crates/wasm/tests/__screenshots__
 .yarn/
+.plans/

crates/core/Cargo.toml

@@ -13,6 +13,7 @@ rust-version.workspace = true
 
 [features]
 std = []
+async = ["dep:async-stream", "dep:futures", "dep:futures-core"]
 geo = ["dep:geo"]
 geoarrow = [
     "dep:geoarrow-array",
@@ -28,13 +29,16 @@ geoarrow = [
 geoparquet = ["geoarrow", "dep:geoparquet", "dep:parquet"]
 
 [dependencies]
+async-stream = { workspace = true, optional = true }
+futures = { workspace = true, optional = true }
 arrow-array = { workspace = true, optional = true, features = ["chrono-tz"] }
 arrow-cast = { workspace = true, optional = true }
 arrow-json = { workspace = true, optional = true }
 arrow-schema = { workspace = true, optional = true }
 bytes.workspace = true
 chrono = { workspace = true, features = ["serde"] }
 cql2.workspace = true
+futures-core = { workspace = true, optional = true }
 geo = { workspace = true, optional = true }
 geo-traits = { workspace = true, optional = true }
 geo-types = { workspace = true, optional = true }