> **Plain-language companion:** [v0.42.0.md](v0.42.0.md)

## v0.42.0 — Hybrid Search & Sparse Vector Aggregates

**Status: Planned.** Derived from [plans/ecosystem/PLAN_PGVECTOR.md](plans/ecosystem/PLAN_PGVECTOR.md) §6.3.

> **Release Theme**
> v0.42.0 completes the vector-aggregate feature set with sparse and
> half-precision types, adds reactive vector-similarity subscriptions for
> real-time anomaly detection, patterns for hybrid-search (BM25 + vector +
> metadata) stream tables, and comprehensive performance benchmarks for
> differential vector workloads.

---

### Features

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| VH-1 | `sparsevec_avg`, `sparsevec_sum`, `halfvec_avg`, `halfvec_sum` aggregates | M | P1 |
| VH-2 | Reactive subscriptions over distance predicates (`embedding <=> q < ε`) | M | P1 |
| VH-3 | Hybrid-search corpus cookbook: BM25 + vector + metadata on one ST | S | P2 |
| VH-4 | Benchmark suite: differential refresh + HNSW throughput, aggregate cost | M | P2 |

**VH-1 — Sparse and half-precision aggregates.**
Extend the algebraic-aggregate framework to support pgvector type variants:
`sparsevec_avg`, `sparsevec_sum`, `halfvec_avg`, and `halfvec_sum`. The running
state for `halfvec_avg` is upcast to `vector(d)` for numerical stability; sparse
variants aggregate over the union of dimensions while treating absent entries as
zero.

**VH-2 — Reactive distance subscriptions.**
Extend reactive subscriptions to support distance-predicate queries where the
query vector is bound at subscription-creation time. The subscription fires only
when rows newly satisfy or cease to satisfy the predicate, avoiding spurious
re-emits on every refresh.

**VH-3 — Hybrid-search cookbook.**
Publish `docs/tutorials/HYBRID_SEARCH_PATTERNS.md` with flat denormalised
corpora, RLS-scoped corpora, tiered search patterns, and performance-tuning
notes. The goal is a copy-paste path to BM25 + vector + metadata retrieval on
incrementally maintained tables.

**VH-4 — Vector benchmark suite.**
Add `benches/pgvector_bench.rs` to measure differential refresh plus ANN insert
throughput, vector aggregate reducer cost, drift-detection overhead, and storage
savings across `vector`, `halfvec`, and `sparsevec` representations.

### Test Coverage

| ID | Title | Effort | Priority |
|----|-------|--------|----------|
| T-VH1 | Integration test: tiered storage (`vector` → `halfvec` → `sparsevec`) | M | P1 |
| T-VH2 | Reactive distance subscriptions: new anomaly alerts | M | P1 |
| T-VH3 | Hybrid-search corpus under write load | M | P2 |

**T-VH1.**
Build a multi-layer stream-table stack and verify all layers refresh correctly
when the source changes. Check both aggregate correctness and ANN query
consistency up to expected quantisation loss.

**T-VH2.**
Create a reactive distance subscription, insert and update rows around a chosen
similarity threshold, and assert that notifications fire only when predicate
truth changes.

**T-VH3.**
Run a hybrid-search corpus under sustained write load, record refresh lag and
query latency, and only write hard latency assertions once the CI baseline is
measured on the actual runner hardware.

### Conflicts & Risks

- **VH-1** needs careful handling of dimension mismatches and all-zero sparse
  vectors. The result definition must be explicit and heavily tested.
- **VH-2** depends on reactive subscription correctness remaining solid after
  the hardening arc; do not layer distance semantics on top of a shaky base.
- **VH-4** should publish measured baselines, not aspirational numbers.

### Exit Criteria

- [ ] VH-1: sparse and half-precision aggregates are implemented and pass equivalence tests against non-incremental computation
- [ ] VH-1: `halfvec_avg` precision is characterized and kept within an explicit error contract
- [ ] VH-2: reactive distance subscriptions fire only on predicate-truth changes
- [ ] VH-3: hybrid-search cookbook published with worked examples
- [ ] VH-4: benchmark suite runs in CI and publishes results alongside other performance data
- [ ] T-VH1: tiered-storage integration tests pass
- [ ] T-VH2: reactive distance tests pass
- [ ] T-VH3: hybrid-search corpus tests pass with baseline-derived assertions
- [ ] Extension upgrade path tested (`0.41.0 → 0.42.0`)
- [ ] `just check-version-sync` passes

---
