Demote rank-bm25 from core dependency to a [bm25] extra (or vendor it)

Problem

rank-bm25 is a required core dependency, but it is effectively abandoned (latest 0.2.2, released Feb 2022; only 4 releases ever) and it backs a non-default scorer. The default retriever is TF-IDF (router.py:503 scorer_backend="tfidf"; registry.py:261 registers TfIdfRetriever with default=True); BM25 is used only when explicitly selected. So every install pulls a 4-year-dormant package for an opt-in backend.

Evidence

• pyproject.toml core dependencies includes rank-bm25>=0.2.
• src/contextweaver/_utils.py:366-398 (BM25Scorer, lazy from rank_bm25 import BM25Okapi).
• Default path never touches it.
• The pyproject rationale ("broadly used in GenAI stacks") overstates necessity for a non-default backend.

Impact

An unmaintained supply-chain node on every install of a security-conscious project. Risk is low (tiny, pure-Python, deterministic), but it's avoidable.

Proposed scope

• Move rank-bm25 to a [bm25] optional extra, using the existing guarded-import + clear-error pattern already used for redis/boto3.
• Or vendor the ~100-line BM25Okapi implementation.
• One-release deprecation note ahead of the move (hence breaking-change).

Acceptance criteria

• Core install has no rank-bm25.
• Selecting the BM25 backend without the extra raises the standard helpful missing-dependency error.

Related

#356 (dependency-constraint policy).

Filed from the 2026-07-03 read-only repository audit (evidence verified at v0.16.0, commit 9f3bc7f).

Start with pyproject.toml and src/contextweaver/_utils.py:366-398, then compare the guarded-import and missing-dependency handling used for redis/boto3. Check the BM25 selection path alongside router.py:503 and registry.py:261. Done means core installs omit rank-bm25 and selecting BM25 without its extra produces the standard helpful missing-dependency error.