feat(retrieval): Phase 6 — integration suite (real valkey-search)

[jamby77]

Phase 6 — Integration suite (real Valkey + valkey-search)

Stacked on #243 (Phase 5) — base is the Phase 5 branch. Final phase of the Retrieval SDK.

What's new

Retriever.integration.test.ts — skip-guarded end-to-end suite against a real valkey-bundle (search module), VALKEY_URL default redis://:devpassword@localhost:6384. Deterministic sha256 fakeEmbed (8-dim).

Covers the full SDK lifecycle:

• createIndex (idempotent — called twice) → upsert → vector query returns the upserted doc
• full hit shape (id/text/fields/finite score)
• query by precomputed vector (embedFn bypass + Float32 serialization)
• TAG and NUMERIC filters narrow correctly
• register/unregister discovery marker round-trip on __betterdb:caches
• health snapshot · delete removes (polls for HNSW propagation) · dropIndex cleans up

Reliability

HNSW indexing/deletion is asynchronous, so beforeAll polls until every doc is queryable and the delete test polls until propagation completes — no fixed sleeps, no order-dependence. Verified green and non-flaky across multiple live runs (9 integration tests; full package suite 101/101). Added iovalkey as a devDependency (the library client is caller-supplied; iovalkey is only used by the test).

Review-driven changes

A pre-PR review flagged indexing-lag races (filter/delete/hit-shape tests), a NaN-passes-typeof score check, and missing FT-capability skip-probe — all fixed; added precomputed-vector + register coverage.

---

Note

Low Risk
Test-only changes and a devDependency; no production SDK behavior or runtime dependencies change.

Overview
Adds end-to-end integration tests for Retriever against a live Valkey instance with the search module (VALKEY_URL, default localhost:6384). Tests skip when Valkey or FT._LIST is unavailable.

The suite exercises index create (idempotent), upsert, vector/text query, precomputed-vector query, TAG/NUMERIC filters, discovery register/unregister, health, delete, and dropIndex. pollUntil waits for async HNSW indexing and deletion instead of fixed sleeps.

iovalkey is added as a devDependency (tests only; the SDK still expects a caller-supplied client). Lockfile picks up the new package.

^{Reviewed by Cursor Bugbot for commit bd4a678. Bugbot is set up for automated code reviews on this repo. Configure here.}