decision needed: how does a local miner reach RAG retrieval without a hosted round-trip?

[JSONbored]

Found during a 2026-07-08 miner-roadmap audit — this is a product/architecture decision, not yet a scoped work item.

The Wave 2 tracker (#2353, Phase 2) itemizes "wire issue-centric RAG retrieval into a scoped MCP tool" for the miner. The pure query-building half of this (buildIssueRagQuery) is extractable today (filed separately, zero risk). But the actual retrieval backend, src/review/rag.ts::retrieveContext, is Vectorize/D1-bound — infrastructure that only exists server-side and isn't something a local miner CLI can reach directly without either:

1. A hosted API round-trip — the miner calls a new authenticated endpoint on the Worker that runs retrieveContext server-side and returns results. Simplest to build, but reopens the "does metadata-only stay metadata-only" question this whole system is built around (the query itself is metadata-only; is exposing retrieval results over the wire still within that boundary, or does it need its own review?).
2. A local embedding/retrieval stack — the miner runs its own lightweight retrieval locally against public issue data. Keeps everything on-device, but is real new engineering (embedding model choice, index format, staying in sync with the live corpus) disproportionate to what this one feature needs.
3. Defer retrieval entirely for v1 — ship the feasibility gate, claim ledger, and plan-DAG work without RAG-assisted analysis, treat this as a later enhancement once the rest of Phase 2 is proven out.

This blocks the "wire into a scoped MCP tool" half of the Phase 2 tracker item — the query-builder extraction can and should proceed independently, but the actual feature can't be finished until this is decided.

What a decision unblocks

• The Phase 2 tracker item ("wire issue-centric RAG retrieval into a scoped MCP tool," 🧩 Wave 2 — Analyze, Plan, Create & Deploy (HELD tracker) #2353) can be properly scoped as a real issue once an approach is chosen
• Whichever approach is picked gets its own follow-up issue(s) with real deliverables

References

• src/review/rag.ts::retrieveContext (the Vectorize/D1-bound backend in question)
• src/review/issue-rag-wire.ts (the miner-facing wrapper already marked as forward groundwork, feat(miner-rag): issue-centric RAG query builder (issue title/body → embeddable query text) #2320)
• Issue 🧩 Wave 2 — Analyze, Plan, Create & Deploy (HELD tracker) #2353, Phase 2 (the tracker item this decision unblocks)
• Roadmap's metadata-only boundary invariant (project memory: "miner's OWN AI harness does the AI, creds stay local" — worth re-checking retrieval-results-over-the-wire against this)

Cloud Readiness cross-reference (added 2026-07-12)

This is the same class of decision as #4943 (hosted discovery-plane fate) and directly informs #5215 (the hosted control-plane architecture spec) and #5217 (auth/identity provider research spike) also in this milestone — all four are instances of the same underlying question: which AMS capabilities can stay local-only for a hosted/multi-tenant future, and which genuinely need a server-side round-trip. Resolve consistently with whatever this milestone settles on for the broader client/server split (#4938).

[linear-code]

JSO-3246