feat(rag): partition-bound retrieval (createPartitionedRAG)

[EmersonBraun]

What

Adds createPartitionedRAG to @agentskit/rag: a RAG instance bound to one partition, so that retrieval from a shared vector store never returns chunks that belong to other partitions.

Why

Shared vector stores need retrieval isolation, for example one partition per repository or tenant. Today search() never forwards a filter to store.search, and RetrieverRequest carries no filter. This adds isolation without changing the stable Retriever contract in ADR 0004 or the existing createRAG behaviour.

How

• Composes the unchanged createRAG with a partition-bound VectorMemory wrapper.
• Every stored chunk gets the reserved _akPartition metadata key and an ID namespaced as a JSON tuple. Deletions use the same namespaced IDs, so one partition can never overwrite or delete another's chunks.
• Searches always forward the core equality filter and also post-filter independently. Chunks with foreign or missing partition metadata are rejected, so the wrapper fails closed even when a store ignores filters.
• The candidate pool is bounded at topK × overfetchFactor (1–16, default 4). A mandatory onDiagnostics callback reports any potentially reduced recall.
• Documented in the new ADR 0043. Stores must preserve metadata and IDs faithfully. Full recall needs a backend that filters natively or physically separate stores.
• Open point for review: a caller-supplied options.filter is currently replaced by the partition filter instead of being combined with it (logical AND).

Reuse

This reuses VectorFilter and VectorSearchOptions.filter from @agentskit/core and composes the existing createRAG. No new dependency, no core contract change and no backend change; the maintainers chose not to add a filter to RetrieverRequest in core.

Type of change

• Bug fix (non-breaking)
• New feature (non-breaking)
• Breaking change (requires RFC reference below)
• Docs only
• Chore / internal

RFC / ADR reference

docs/architecture/adrs/0043-partition-bound-rag.md (Proposed)

Validation

• Every acceptance criterion has contract or edge-case test evidence (pnpm test): two partitions never leak, tested with real fileVectorMemory (including reopening it) and with synthetic stores that honour and that ignore filters; bounded over-fetch; diagnostics.
• All applicable documented repository gates pass on this commit (174 RAG tests, coverage 97.32%, and the 52 repository quality gates via the pre-push hook)
• Type check (pnpm lint)
• Bundle size within budget (all four RAG gzip targets)
• Public API JSDoc updated and coverage passes (public-api-v1.json lists the three new exports)
• Changeset created (pnpm changeset) — minor for @agentskit/rag
• Docs updated (package README, reference and for-agents pages)
• No tests disabled or skipped to pass a gate

[github-actions]

Lighthouse

URL	Performance	Accessibility	Best practices	SEO
http://127.0.0.1:3000/	60	100	96	100
http://127.0.0.1:3000/docs	82	100	96	100
http://127.0.0.1:3000/docs/get-started/getting-started/quickstart	83	100	96	100
http://127.0.0.1:3000/stack	93	100	96	100
http://127.0.0.1:3000/showcase	91	100	96	100

Run by .github/workflows/lighthouse.yml.

[github-actions]

Lighthouse

URL	Performance	Accessibility	Best practices	SEO
http://127.0.0.1:3000/	55	100	96	100
http://127.0.0.1:3000/docs	81	100	96	100
http://127.0.0.1:3000/docs/get-started/getting-started/quickstart	82	100	96	100
http://127.0.0.1:3000/stack	95	100	96	100
http://127.0.0.1:3000/showcase	89	100	96	100

Run by .github/workflows/lighthouse.yml.

[github-actions]

Lighthouse

URL	Performance	Accessibility	Best practices	SEO
http://127.0.0.1:3000/	75	100	96	100
http://127.0.0.1:3000/docs	87	100	96	100
http://127.0.0.1:3000/docs/get-started/getting-started/quickstart	87	100	96	100
http://127.0.0.1:3000/stack	96	100	96	100
http://127.0.0.1:3000/showcase	96	100	96	100

Run by .github/workflows/lighthouse.yml.