feat(search): expose per-arm participation evidence

[ohdearquant]

Summary

• add typed arm_participation evidence for the text and vector KG search arms with ran, skipped, and error status plus bounded final candidate counts
• preserve the evidence on complete, partial, zero-match, degraded-empty, presentation, and frame-budget paths without changing filtering, fusion, or deterministic ranking
• document exact-name presence checks and align degraded arm status with ADR-130 / fix(mcp): classify and pace backend search timeouts #2176 bounded backend cause vocabulary
• cover exact-name text hits, long keyword-dense zero hits, vector and both-source counting, partial results, degraded-empty failures, and diagnostic omission

Verification

• cargo test --workspace
• cargo test -p khive-mcp --lib (449 passed)
• cargo test -p kkernel coordinator::tests (63 passed)
• cargo check -p kkernel --all-targets
• cargo clippy --workspace --all-targets -- -D warnings
• cargo fmt --all -- --check
• git diff --check

Closes #1935

[ohdearquant]

Both arm statuses are derived from an undifferentiated backend error, and the vector discriminator is a config flag

The statuses are computed at crates/khive-mcp/src/server.rs:196-203:

let text_failed = result.per_backend.iter().any(|b| b.error.is_some());
let vector_failed = result.per_backend.iter().any(|b| b.vector_selected && b.error.is_some());

text_failed is "any backend errored" — it discriminates neither by arm nor by backend. And
vector_selected is not an execution fact: crates/kkernel/src/coordinator/service.rs:162-166
derives it from entry.runtime.config().embedding_model.is_some(), i.e. whether that backend is
configured with an embedding model, regardless of whether the vector arm ever ran.

Put those together in a coordinator fan-out — the case from_result exists to serve, per its own
doc comment at server.rs:160-163. Backend A succeeds, backend B fails. The response still carries
A's hits, but text is reported error, and vector is reported error as well whenever B merely
has an embedding model configured, whatever actually failed there. Relatedly, vector_selected at
server.rs:179-182 is an .any() across backends, so a single embedding-configured backend marks
the vector arm ran for a response in which other backends never ran it.

This is the failure mode the field exists to prevent. The evidence is right in the common
single-backend case and wrong exactly when a backend is degraded, which is when someone reads it.
The fix is to carry each arm's own outcome from the point that arm finishes, per backend, rather
than reconstructing it from an aggregate error plus a configuration flag — with a regression test
for a fan-out in which one backend fails.

One thing to note so the mechanism is not mis-stated: within a single backend, a vector failure
aborts the whole hybrid search (crates/khive-runtime/src/retrieval.rs:746 propagates with ?), so
the text hits are discarded rather than surviving beside a vector error. The cross-backend path
above is the reachable one.

Documented cause vocabulary does not match the code

docs/adr/ADR-130-search-response-completeness-and-ranking-evidence.md:802 and
docs/guide/api-reference.md:483 both promise a closed timeout | backend_error vocabulary. The
only production emitter, backend_errors_value at crates/khive-mcp/src/server.rs:395, hardcodes
"kind": "backend_error", and no production site emits timeout — the other occurrences in the
tree are test code. A caller cannot distinguish a timeout from any other backend failure. Either
propagate a typed cause or drop the two-value promise from both documents.

Verified and sound

• No filtering, fusion, ordering or short-circuit behaviour changed. Evidence gathering reads an
  already-built result and cannot force an arm to run or to complete.
• Zero is distinguishable across the three cases when the operation completes: an arm that ran and
  matched nothing is ran, 0, a skipped vector arm is skipped, 0, and a degraded selected arm is
  error, 0. An arm that ran, matched rows, and had them all filtered out reports ran, 0.
• Evidence is attached on the success, coordinator-partial, complete-empty and incomplete paths, and
  arm_participation is in the survivor key list for frame omission (server.rs:4012-4025), so it
  survives a trimmed frame.
• observe_result sets only the counts; it does not override the statuses.

Non-blocking notes

• Saturation is invisible. search_arm_candidate_counts (server.rs:312-325) folds over the final
  serialized result, so each count is bounded by the caller's limit — which
  docs/guide/api-reference.md:484-486 does document. What neither documents nor marks is the
  boundary case: a count that equals limit is indistinguishable from one that was clamped there,
  and nothing in the response says which. The sibling bounded-count work in this area publishes an
  explicit saturation flag for exactly this reason; the same treatment would fit here.
• Tests cover envelope placement, source counting, complete-empty, degraded-empty and presentation.
  They do not cover a fan-out with one failing backend, a count sitting at the limit, or an
  end-to-end frame-budget trim; the frame tests are synthetic helper tests.

No builds or tests were run for this pass; every finding above is from source reading.

[ohdearquant]

Automated review. Posted by this repository's automated pull-request review pipeline; this is not a human read and does not gate the merge by itself.

Verdict on head 821eb94: REQUEST-CHANGES, 1 blocking finding. Finding details are delivered to the review's recipients rather than posted here. Do not merge this head while blocking findings are outstanding; a pipeline comment on a newer head supersedes this one.

[ohdearquant]

Automated review. Posted by this repository's automated pull-request review pipeline; this is not a human read and does not gate the merge.

Verdict on current head: APPROVE, zero blocking findings. This is a comment, not an approval — a human reviewer decides whether to approve and merge.

[oceanwaves630]

STAMPING, not reviewing.

This approval executes the standing khive-oss stamp lane on a mechanical gate; it is not an independent code review, and it carries no judgment of my own about the change.

Gate read at head deb224e98fb085c3bb3b5d8c7c37bf346bf4ef21:

• complete daemon verdict at this exact head (.md/.json/.process.jsonl all present)
• decision APPROVE, degraded False
• 0 blocking; 1 graded finding, maintainability/minor, non-blocking — read it before merging, "0 blocking" is not "no findings"
• CI at this head: 21 passing, 0 failing, 0 pending
• base main, open, not a draft
• no CHANGES_REQUESTED outstanding from any account

Merge with --match-head-commit deb224e98fb085c3bb3b5d8c7c37bf346bf4ef21; if the head moves, this stamp does not carry.