test(retrieval): add lexical controls and ripgrep comparator

[jeremydixon22]

What this tests

• turns the embedded, Python HTTP, and JavaScript HTTP quickstarts into true zero-embedding lexical controls
• runs both HTTP quickstarts against one isolated Release server in CI
• compares the bounded ripgrep adapter with Vyral lexical any, all, and prefix policies on one labeled 2,016-document corpus
• retains all 18 query results plus quality, latency, setup, storage, freshness, citation, and sensitive-path evidence
• independently recomputes receipt metrics and proves CI rejects altered evidence

Results

• ripgrep: 1.00 recall, returned precision, and MRR on all 8 exact-literal cases
• Vyral lexical all: the same exact-literal quality and 0.75 recall on reordered/separated terms where ripgrep scored 0
• Vyral lexical prefix: 1.00 recall on prefix cases where ripgrep scored 0
• warm p95: ripgrep 33.398 ms; Vyral lexical all 1.508 ms; Vyral prefix 1.738 ms
• setup: ripgrep adapter 2.668 ms with no copied index; Vyral ingest 29,158.337 ms for this small-record fixture
• freshness: ripgrep saw the committed edit without refresh; Vyral remained stale until the changed record was upserted

Decision and contract boundary

The evidence admits one experimental use case: bounded exact-literal lookup over an authorized, rapidly changing local code or Markdown tree when copying that tree into an index is not justified. Indexed Vyral remains the appropriate path for reordered terms, prefixes, filters, tenant boundaries, snapshots, and lower post-index latency.

The integration remains outside the stable OpenAPI, schema, SDK-catalog, REST, and MCP surfaces. It does not expose filesystem search automatically.

Evidence

• benchmarks/retrieval/ripgrep-vs-vyral-local-2026-08-11.json
• scripts/benchmark-ripgrep-retrieval.py
• scripts/verify-ripgrep-retrieval-report.py
• scripts/verify-lexical-http-quickstarts.sh
• scripts/verify-python-runtime.sh (227 tests, 79.0% branch coverage, strict mypy, wheel/sdist clean-install checks)
• scripts/verify-public-export.sh
• python3 scripts/verify-markdown-links.py --all .
• JavaScript client check, typecheck, and 61 tests
• Python client 62 tests