Feat/vep 0005 richer scopes

[jsdevninja]

What changed

Introduces structured ArtifactScope (visibility, project, agent) on Claim and Source, plus viewer-context filtering in kb.search, kb.context, vouch search, and vouch context. A new scoping module resolves viewer context (request param → env → config) and filters claim/source hits post-retrieval. JSON schemas regenerated; kb.capabilities advertises scoping.

Why

A single flat scope enum can't express which project or agent owns an artifact. With multi-agent KBs and deterministic sync, retrieval surfaces unrelated project claims and can't distinguish one agent's private notes from another's. VEP-0005 defines structured scopes so shared KBs stay usable.

Fixes #189

What might break

• On-disk layout: No file moves. Existing scope: project strings still parse; artifacts rewrite to the object form on next write (lazy migration).
• kb.search / kb.context behavior: Viewers with project or agent set see fewer hits (intentional). Default viewer (no project/agent) behaves as before.
• JSONL kb.search result shape: Now matches MCP — {backend, viewer, hits} instead of a bare hit list. JSONL clients that expected an array need to read result.hits.
• JSON Schemas: claim / source scope changed from enum string to object.
• Not access control: private filters retrieval only; artifacts remain plaintext on disk.

VEP

VEP-0005: Richer scopes on Claim/Source (draft — should be accepted or marked in-progress before merge)

Tests

• make check passes locally (lint + mypy + pytest)
• New / changed behaviour has a test (tests/test_scoping.py; updated JSONL/embedding search tests)
• CHANGELOG.md updated under ## [Unreleased]

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f5936c34-b494-4d5b-9d31-e75bbc4ab7c0

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}