feat(retrieval): Phase 2 — idempotent index lifecycle

[jamby77]

Phase 2 — Index lifecycle (idempotent)

Adds Retriever to @betterdb/retrieval with the three index-lifecycle methods, built over the Phase 0 @betterdb/valkey-search-kit parsers and Phase 1's buildFtCreateArgs.

Methods

• createIndex() — probes FT.INFO; no-ops when the index exists, issues FT.CREATE when absent, and rethrows non-not-found FT.INFO errors instead of blindly creating.
• dropIndex() — issues FT.DROPINDEX, swallows isIndexNotFoundError, rethrows other errors.
• describeIndex() — parses FT.INFO into a typed IndexDescription (name, dims, numDocs, indexingState) via the kit's parseFtInfoStats / parseDimensionFromInfo; propagates the error when the index is missing.

Public API

Exports Retriever plus RetrieverClient, RetrieverOptions, IndexDescription.

Tests

8 unit tests (mocked client), full package suite 42/42 green, tsc --noEmit clean.

Scope / follow-ups

• Real-Valkey coverage is deferred to Phase 6 (integration suite); these are mocked unit tests per the plan.
• dims comes from the schema here; embedFn-based dims inference is Phase 3.
• describeIndex surfaces the raw error on a missing index (caller checks existence via createIndex first); a typed not-found variant can come with the query layer if needed.
• Concurrent create/drop races are not guarded at this layer (single-caller usage assumed), mirroring where semantic-cache adds a semaphore — revisit if shared-instance concurrency becomes a requirement.

---

Note

Low Risk
New retrieval-layer API with mocked tests only; no changes to auth, persistence, or existing call paths.

Overview
Introduces Retriever in @betterdb/retrieval as the public API for Valkey search index lifecycle, wired to existing buildFtCreateArgs / indexName and @betterdb/valkey-search-kit parsers.

createIndex() probes FT.INFO first: it skips FT.CREATE when the index exists, creates only on index-not-found, and rethrows other FT.INFO failures (e.g. LOADING). dropIndex() runs FT.DROPINDEX and ignores missing-index errors. describeIndex() maps FT.INFO to IndexDescription (name, dims, numDocs, indexingState) and surfaces errors when the index is absent.

The package entrypoint now exports Retriever plus RetrieverClient, RetrieverOptions, and IndexDescription. Eight mocked unit tests cover these behaviors.

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