feat(hub): read-only KB subscriptions — federate search without copying (#610)

[Tet-9]

What changed

Adds read-only KB subscriptions: vouch subscribe <kb>, vouch unsubscribe <kb>, and vouch subscriptions list. A subscribed KB's approved knowledge is queried alongside the local KB in kb.search and kb.context and merged into results — live, read-only, never copied. Federated hits are namespaced (<kb_id>:<artifact_id>), tagged with origin_kb_id/origin_kb_name/trust_level, and capped by a budget_share config knob so they only fill leftover slots and can never displace an already-ranked local result. Subscriptions are one hop only — a federated call never itself federates.

Why

Today sharing knowledge between KBs means copying it via vouch hub export/import: the same fact ends up duplicated, drifts independently, and needs re-review on every upstream edit. For a review-gated system, subscription is the safer primitive than import — a federated search hit is not a write, so there's nothing for the review gate to guard, no new bypass risk. Closes #610.

What might break

• No existing on-disk file changes shape, and no existing file moves.
• ContextItem gains one new optional field, trust_level (default None) — additive, not a breaking change to the existing shape.
• kb.search / kb.context can now return additional hits (tagged federated: true) when the KB has subscriptions configured — opt-in and off by default, so behavior for any KB with no subscriptions.json is unchanged.
• No change to kb.propose_* / kb.approve / review-gate semantics — federated artifacts are read-only end to end (not proposable, not approvable, not supersedable locally).

VEP

Not yet — checking whether this qualifies as a surface change requiring one before merge.

Tests

• make check passes locally (lint + mypy + pytest)
• New / changed behaviour has a test (tests/test_subscriptions.py, 14 tests: subscribe/unsubscribe/list, one-hop enforcement, budget cap, dead-subscription handling, origin/trust tagging)
• CHANGELOG.md updated under ## [Unreleased]

[plind-junior]

closing this — it is not finished by its own account, and the unfinished parts are the ones that decide whether it is safe.

the PR's own checklist has make check unticked and CHANGELOG.md unticked, diff coverage (100% of changed python) is failing on CI, and the VEP section reads "Not yet — checking whether this qualifies as a surface change requiring one before merge." that last one is not a formality here. this adds kb.search / kb.context results that are not local artifacts, namespaced ids (<kb_id>:<artifact_id>), and a new optional trust_level field on ContextItem. whether that needs a VEP is exactly the question to settle before review, not during.

the design instinct is right and i want to say so clearly: subscription really is the safer primitive than import for a review-gated system, and "a federated search hit is not a write, so there is nothing for the gate to guard" is the correct framing. one-hop-only, budget-capped so federated hits can never displace a ranked local result, and read-only end to end are all the right constraints.

but the thing i would need to convince myself of before merging is the one the description asserts rather than demonstrates: that a federated id can never reach a write path. kb.propose_* taking a <kb_id>:<artifact_id> as a claim or source reference, kb.supersede on a federated id, a page citing one — each needs to fail closed, and the 14 tests listed cover subscribe/unsubscribe/list, one-hop, budget, dead subscriptions and tagging, but not that. with 100% diff coverage failing, i cannot tell from CI either.

so: get the matrix and coverage green, finish the CHANGELOG entry, settle the VEP question, and add the tests that pin a federated id being refused by every write surface. i will review it properly then — #610 is a good issue and this is a credible answer to it.

[Tet-9]

closing this — it is not finished by its own account, and the unfinished parts are the ones that decide whether it is safe.

the PR's own checklist has make check unticked and CHANGELOG.md unticked, diff coverage (100% of changed python) is failing on CI, and the VEP section reads "Not yet — checking whether this qualifies as a surface change requiring one before merge." that last one is not a formality here. this adds kb.search / kb.context results that are not local artifacts, namespaced ids (<kb_id>:<artifact_id>), and a new optional trust_level field on ContextItem. whether that needs a VEP is exactly the question to settle before review, not during.

the design instinct is right and i want to say so clearly: subscription really is the safer primitive than import for a review-gated system, and "a federated search hit is not a write, so there is nothing for the gate to guard" is the correct framing. one-hop-only, budget-capped so federated hits can never displace a ranked local result, and read-only end to end are all the right constraints.

but the thing i would need to convince myself of before merging is the one the description asserts rather than demonstrates: that a federated id can never reach a write path. kb.propose_* taking a <kb_id>:<artifact_id> as a claim or source reference, kb.supersede on a federated id, a page citing one — each needs to fail closed, and the 14 tests listed cover subscribe/unsubscribe/list, one-hop, budget, dead subscriptions and tagging, but not that. with 100% diff coverage failing, i cannot tell from CI either.

so: get the matrix and coverage green, finish the CHANGELOG entry, settle the VEP question, and add the tests that pin a federated id being refused by every write surface. i will review it properly then — #610 is a good issue and this is a credible answer to it.

You may reopen it now please, just had something to deal with was why it was left uncompleted

[Tet-9]

closing this — it is not finished by its own account, and the unfinished parts are the ones that decide whether it is safe.
the PR's own checklist has make check unticked and CHANGELOG.md unticked, diff coverage (100% of changed python) is failing on CI, and the VEP section reads "Not yet — checking whether this qualifies as a surface change requiring one before merge." that last one is not a formality here. this adds kb.search / kb.context results that are not local artifacts, namespaced ids (<kb_id>:<artifact_id>), and a new optional trust_level field on ContextItem. whether that needs a VEP is exactly the question to settle before review, not during.
the design instinct is right and i want to say so clearly: subscription really is the safer primitive than import for a review-gated system, and "a federated search hit is not a write, so there is nothing for the gate to guard" is the correct framing. one-hop-only, budget-capped so federated hits can never displace a ranked local result, and read-only end to end are all the right constraints.
but the thing i would need to convince myself of before merging is the one the description asserts rather than demonstrates: that a federated id can never reach a write path. kb.propose_* taking a <kb_id>:<artifact_id> as a claim or source reference, kb.supersede on a federated id, a page citing one — each needs to fail closed, and the 14 tests listed cover subscribe/unsubscribe/list, one-hop, budget, dead subscriptions and tagging, but not that. with 100% diff coverage failing, i cannot tell from CI either.
so: get the matrix and coverage green, finish the CHANGELOG entry, settle the VEP question, and add the tests that pin a federated id being refused by every write surface. i will review it properly then — #610 is a good issue and this is a credible answer to it.

You may reopen it now please, just had something to deal with was why it was left uncompleted

Then I'd complete everything that has do with it asap