Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

feat(hub): add opt-in byte-exact answer evidence receipts (#2932)

Raghuvar Karthik Durga344a95f61bc6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a7785ea2b..fb95d3a4c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
+- Opt-in hub answer evidence receipts (Refs #1789, #1786): Rust callers can
+ bind exact UTF-8 excerpts to pinned source bytes and export SHA-256/JCS
+ trace reports. MCP ask/def accepts trace identities through `evidence`;
+ unavailable source bytes or calibration explicitly abstain and escalate.
+ Default answer and hit wire fields are unchanged.
+
- Opt-in advisory Claude Code search hints with `xerj init --hooks` on macOS/Linux
(Refs #2642): Grep/Glob and repeated Read can suggest a cited search scoped to
the indexed folder and configured loopback node, with a per-session quota.
diff --git a/docs/hub-v2-grpc-mcp-notes.md b/docs/hub-v2-grpc-mcp-notes.md
index 8dfebea11..c05346365 100644
--- a/docs/hub-v2-grpc-mcp-notes.md
+++ b/docs/hub-v2-grpc-mcp-notes.md
@@ -12,6 +12,39 @@ This PR (branch `feat/hub-v2-grpc-contract`, based on `feat/hub-v2-base`) does
`add_service` registration in `grpc.rs`/`main.rs`, and the MCP tools are
**deferred to step 5/7**. Generated-but-unimplemented scaffolding is intentional.
+## Opt-in answer evidence receipts (#1789, #1786)
+
+The implemented MCP `xerj_hub_ask` and `xerj_hub_def` tools accept an optional
+`evidence` object with required `session_id` and `tool_call_id` strings and an
+optional `p_min` probability (default `0.8`). Identities are caller supplied;
+each result is a standalone, one-entry report, not a persisted session log.
+When an answer is available, this adds only `structuredContent.evidence_receipt`,
+a `xerj-trace-evidence/v1` report; omitting the option preserves the entire
+existing result. Routing hints and errors without an answer remain unchanged.
+The receipt records the exact MCP text, including notices.
+
+The shared Rust bridge is `Answer::evidence_report(AnswerEvidence, resolve)`;
+`Hit::pinned_citation` anchors an exact excerpt on its declared one-based line.
+The resolver must provide original UTF-8 bytes from the answer's immutable
+`pin_sha` and hit file, plus the repository identity. Byte offsets and SHA-256
+hashes retain CRLF and multibyte characters without normalization. A mismatched
+excerpt, invalid pin/path or resolver error returns an error. An unavailable
+source is represented by `None` and yields an explicit coverage gap.
+`TraceEvidenceReport::to_jcs` emits RFC 8785 canonical JSON; `verify` rechecks the
+receipt and resolves each citation against the pinned file bytes.
+
+Claims bind retrieved excerpt text, not semantic entailment. Callers must
+separately assess question coverage and provide a held-out, in-domain
+`Confidence`; ranking scores are never converted to probabilities.
+Empty hits, missing source/calibration, low calibrated confidence, coverage
+gaps, truncated answers, and separately rendered values without an assessment
+abstain and escalate. Current MCP index records do not contain original pinned
+files or an in-domain calibration assessment, so MCP receipts conservatively
+abstain and escalate even when hits exist. MCP does not read working-tree
+files, fetch source files, or accept caller-supplied confidence/bytes.
+This is additive wiring, not a new calibration study or completion of either
+issue's evaluation gates. No gRPC field or default `Answer`/`Hit` field changes.
+
## Why the fields are frozen
Proto field numbers are a permanent wire contract. Step 11 of the plan lists
diff --git a/engine/crates/xerj-common/src/hub_evidence.rs b/engine/crates/xerj-common/src/hub_evidence.rs
index 8fcbb7e36..e5b14f4f7 100644
--- a/engine/crates/xerj-common/src/hub_evidence.rs
+++ b/engine/crates/xerj-common/src/hub_evidence.rs
@@ -7,6 +7,7 @@
use crate::calibration::{
ece_from_curve, reliability_curve, CalibrationPair, IsotonicCalibration, CALIBRATION_BINS,
};
+use crate::hub::{Answer, Hit};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use std::collections::HashSet;
@@ -448,6 +449,127 @@ impl TraceEvidenceReport {
}
}
+/// Original file bytes resolved by a trusted caller at `Answer::pin_sha`.
+/// Never populate this from rendered snippets or a mutable working tree.
+pub struct PinnedSource {
+ pub repository: String,
+ pub bytes: Vec<u8>,
+}
+
+/// Caller-owned invocation identity, exact displayed text and coverage assessment.
+/// Search scores are not calibrated probabilities. Missing calibration fails closed.
+pub struct AnswerEvidence {
+ pub session_id: String,
+ pub tool_call_id: String,
+ pub question: String,
+ pub shown_answer: String,
+ pub confidence: Option<Confidence>,
+ pub p_min: f64,
+ /// An empty list asserts that the caller assessed question-specific coverage.
+ pub coverage_gaps: Vec<String>,
+}
+
+impl Hit {
+ /// Pin only an exact UTF-8 excerpt on the hit's declared, one-based line.
+ /// Indentation is allowed; newline normalization and searching other lines are not.
+ pub fn pinned_citation(
+ &self,
+ corpus: &str,
+ commit: &str,
+ source: &PinnedSource,
+ ) -> Result<PinnedCitation> {
+ require(
+ self.line > 0 && !self.text.is_empty(),
+ "hit has no exact excerpt",
+ )?;
+ let text = std::str::from_utf8(&source.bytes)
+ .map_err(|_| EvidenceError::Invalid("source is not UTF-8"))?;
+ let start = if self.line == 1 {
+ 0
+ } else {
+ text.match_indices('\n')
+ .nth(self.line as usize - 2)
+ .map(|(i, _)| i + 1)
+ .ok_or(EvidenceError::Invalid("hit line beyond source"))?
+ };
+ let offset = text[start..]
+ .find(&self.text)
+ .filter(|&offset| !text[start..start + offset].contains('\n'))
+ .ok_or(EvidenceError::Invalid(
+ "hit excerpt does not match source line",
+ ))?;
+ let byte_start = start + offset;
+ PinnedCitation::from_bytes(
+ corpus.into(),
+ source.repository.clone(),
+ commit.into(),
+ self.file.clone(),
+ &source.bytes,
+ byte_start..byte_start + self.text.len(),
+ )
+ }
+}
+
+impl Answer {
+ /// Build a separate receipt without changing any legacy answer or hit fields.
+ ///
+ /// `resolve` must select the original file using this answer's corpus and
+ /// immutable pin plus the hit's file, not HEAD. `None` means unavailable;
+ /// resolution/integrity errors are returned, never silently downgraded.
+ /// Claims record retrieved excerpts, not inferred semantic entailment.
+ pub fn evidence_report(
+ &self,
+ context: AnswerEvidence,
+ mut resolve: impl FnMut(&Hit) -> Result<Option<PinnedSource>>,
+ ) -> Result<TraceEvidenceReport> {
+ let mut entry = TraceEntry {
+ tool_call_id: context.tool_call_id,
+ question: context.question,
+ shown_answer: context.shown_answer,
+ claims: Vec::new(),
+ citations: Vec::new(),
+ confidence: context.confidence,
+ p_min: context.p_min,
+ coverage_gaps: context.coverage_gaps,
+ abstain: true,
+ escalate: true,
+ };
+ if self.truncated {
+ entry.coverage_gaps.push("answer was truncated".into());
+ }
+ for (i, hit) in self.hits.iter().enumerate() {
+ if hit.text.trim().is_empty() {
+ entry.coverage_gaps.push(format!("hit {i} has no excerpt"));
+ continue;
+ }
+ let mut evidence_indices = Vec::new();
+ if let Some(source) = resolve(hit)? {
+ let citation = hit.pinned_citation(&self.corpus, &self.pin_sha, &source)?;
+ evidence_indices.push(
+ u32::try_from(entry.citations.len())
+ .map_err(|_| EvidenceError::Invalid("too many citations"))?,
+ );
+ entry.citations.push(citation);
+ } else {
+ entry
+ .coverage_gaps
+ .push(format!("hit {i}: pinned source unavailable"));
+ }
+ if hit.value.is_some() {
+ entry
+ .coverage_gaps
+ .push(format!("hit {i}: separate value not assessed"));
+ }
+ entry.claims.push(Claim {
+ id: format!("hit-{i}"),
+ text: hit.text.clone(),
+ evidence_indices,
+ });
+ }
+ TraceEvidenceReport::new(context.session_id, vec![entry.finalize()?])
+ }
+}
+
#[cfg(test)]
mod tests {
use super::*;
@@ -510,6 +632,119 @@ mod tests {
TraceEvidenceReport::new("session-1".into(), vec![entry()]).unwrap()
}
+ fn answer() -> Answer {
+ use crate::hub::{AnswerMode, AnsweredFrom, LicenceClass};
+ Answer {
+ corpus: "sample".into(),
+ pin_sha: "a".repeat(40),
+ pin_date: "2026-11-04".into(),
+ age_days: 0,
+ licence_spdx: "MIT".into(),
+ licence_class: LicenceClass::AdaptWithAttribution,
+ answered_from: AnsweredFrom::LocalPack,
+ mode: AnswerMode::How,
+ hits: vec![Hit {
+ file: "src/example.txt".into(),
+ line: 2,
+ kind: "passage".into(),
+ text: "second é\r\n".into(),
+ value: None,
+ score: 100.0,
+ licence_warning: None,
+ }],
+ truncated: false,
+ warnings: vec![],
+ }
+ }
+
+ fn answer_context(a: &Answer) -> AnswerEvidence {
+ AnswerEvidence {
+ session_id: "session-1".into(),
+ tool_call_id: "call-1".into(),
+ question: "What is on line two?".into(),
+ shown_answer: crate::hub::render(a),
+ confidence: Some(confidence()),
+ p_min: 0.8,
+ coverage_gaps: vec![],
+ }
+ }
+
+ fn source() -> PinnedSource {
+ PinnedSource {
+ repository: "owner/repo".into(),
+ bytes: FILE.to_vec(),
+ }
+ }
+
+ #[test]
+ fn answer_bridge_pins_utf8_crlf_and_preserves_wire_fields() {
+ let a = answer();
+ let before = serde_json::to_value(&a).unwrap();
+ let r = a
+ .evidence_report(answer_context(&a), |_| Ok(Some(source())))
+ .unwrap();
+ let e = &r.entries[0];
+ assert!(!e.abstain && !e.escalate);
+ assert_eq!(e.shown_answer, crate::hub::render(&a));
+ assert_eq!(e.claims[0].evidence_indices, vec![0]);
+ let c = &e.citations[0];
+ assert_eq!((c.byte_start, c.byte_end), (7, 18));
+ assert_eq!(c.span_sha256, sha256("second é\r\n".as_bytes()));
+ c.verify_bytes(FILE).unwrap();
+ let jcs = r.to_jcs().unwrap();
+ assert_eq!(jcs, canonical(&r).unwrap());
+ TraceEvidenceReport::verify(&jcs, |_| Ok(FILE.to_vec())).unwrap();
+ assert_eq!(serde_json::to_value(&a).unwrap(), before);
+ assert_eq!(before.as_object().unwrap().len(), 11);
+ assert_eq!(before["hits"][0].as_object().unwrap().len(), 7);
+ let round_trip: Answer = serde_json::from_value(before.clone()).unwrap();
+ assert_eq!(serde_json::to_value(round_trip).unwrap(), before);
+ }
+
+ #[test]
+ fn answer_bridge_abstains_for_missing_hits_sources_and_calibration() {
+ for case in 0..6 {
+ let mut a = answer();
+ let mut context = answer_context(&a);
+ match case {
+ 0 => a.hits.clear(),
+ 1 => context.confidence.as_mut().unwrap().p_cal = 0.2,
+ 2 => context.confidence = None,
+ 3 => context.coverage_gaps.push("question not covered".into()),
+ 4 => a.truncated = true,
+ _ => {}
+ }
+ let r = a
+ .evidence_report(context, |_| {
+ Ok(if case == 5 { None } else { Some(source()) })
+ })
+ .unwrap();
+ assert!(r.entries[0].abstain && r.entries[0].escalate, "case {case}");
+ r.to_jcs().unwrap();
+ }
+ }
+
+ #[test]
+ fn answer_bridge_rejects_wrong_lines_rendered_text_and_resolution_errors() {
+ let mut a = answer();
+ for line in [0, 1, 3, 10] {
+ a.hits[0].line = line;
+ assert!(a
+ .evidence_report(answer_context(&a), |_| Ok(Some(source())))
+ .is_err());
+ }
+ a.hits[0].line = 2;
+ a.hits[0].text = "second é\n".into();
+ assert!(a
+ .evidence_report(answer_context(&a), |_| Ok(Some(source())))
+ .is_err());
+ assert!(a
+ .evidence_report(answer_context(&a), |_| {
+ Err(EvidenceError::Resolution("pin unavailable".into()))
+ })
+ .is_err());
+ }
+
#[test]
fn exact_bytes_lines_and_round_trip() {
let c = citation();
diff --git a/engine/crates/xerj-mcp/src/hub.rs b/engine/crates/xerj-mcp/src/hub.rs
index f920fd4a7..9f1b25992 100644
--- a/engine/crates/xerj-mcp/src/hub.rs
+++ b/engine/crates/xerj-mcp/src/hub.rs
@@ -31,6 +31,7 @@
//! With no cached copy the tool says to run `xerj hub sync`.
use serde_json::{json, Value};
+use xerj_common::hub_evidence::AnswerEvidence;
use xerj_hub::ask::{
self, AskArgs, AskOutcome, ModeRequest, EXIT_NEEDS_DECISION, FIND_DEFAULT_K, FIND_MAX_K,
};
@@ -100,7 +101,8 @@ pub fn specs() -> Vec<Value> {
"minimum": 1,
"maximum": MAX_K,
"description": "Max hits to return (default 5)."
- }
+ },
+ "evidence": evidence_schema()
},
"required": ["slug", "symbol"]
}
@@ -133,7 +135,8 @@ pub fn specs() -> Vec<Value> {
"minimum": 1,
"maximum": MAX_TOKENS_CAP,
"description": "Soft output budget for the rendered answer (about 4 characters a token)."
- }
+ },
+ "evidence": evidence_schema()
},
"required": ["question"]
}
@@ -141,6 +144,51 @@ pub fn specs() -> Vec<Value> {
]
}
+fn evidence_schema() -> Value {
+ json!({
+ "type": "object",
+ "description": "Opt in to structuredContent.evidence_receipt. Supply caller trace identities. Without original pinned bytes and an in-domain calibration assessment, the receipt abstains and escalates; search scores are never probabilities.",
+ "properties": {
+ "session_id": { "type": "string", "minLength": 1, "maxLength": MAX_INPUT_BYTES },
+ "tool_call_id": { "type": "string", "minLength": 1, "maxLength": MAX_INPUT_BYTES },
+ "p_min": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.8 }
+ },
+ "required": ["session_id", "tool_call_id"],
+ "additionalProperties": false
+ })
+}
+
+struct EvidenceRequest {
+ session_id: String,
+ tool_call_id: String,
+ p_min: f64,
+}
+
+fn evidence_arg(args: &Value) -> Result<Option<EvidenceRequest>, String> {
+ let Some(value) = args.get("evidence") else {
+ return Ok(None);
+ };
+ let object = value.as_object().ok_or("`evidence` must be an object")?;
+ if object
+ .keys()
+ .any(|key| !matches!(key.as_str(), "session_id" | "tool_call_id" | "p_min"))
+ {
+ return Err("unknown `evidence` field".into());
+ }
+ let p_min = match value.get("p_min") {
+ None => 0.8,
+ Some(v) => v
+ .as_f64()
+ .filter(|n| n.is_finite() && (0.0..=1.0).contains(n))
+ .ok_or("`p_min` must be a probability from 0 to 1")?,
+ };
+ Ok(Some(EvidenceRequest {
+ session_id: text_arg(value, "session_id")?,
+ tool_call_id: text_arg(value, "tool_call_id")?,
+ p_min,
+ }))
+}
+
/// Dispatch one `xerj_hub_*` call; `None` when `name` is not a hub tool.
pub async fn call(ctx: &Ctx, name: &str, args: &Value) -> Option<Value> {
let result = match name {
@@ -223,11 +271,12 @@ async fn def(ctx: &Ctx, args: &Value) -> Result<Value, String> {
let slug = slug_arg(args, "slug", true)?.unwrap_or_default();
let symbol = text_arg(args, "symbol")?;
let k = int_arg(args, "k", MAX_K)?;
+ let evidence = evidence_arg(args)?;
let mut a = AskArgs::new(symbol.clone());
a.corpus = Some(slug);
a.mode = ModeRequest::Def(symbol);
a.k = k.map(|n| n as usize);
- Ok(run(ctx, a).await)
+ Ok(run(ctx, a, evidence).await)
}
async fn ask_tool(ctx: &Ctx, args: &Value) -> Result<Value, String> {
@@ -251,16 +300,17 @@ async fn ask_tool(ctx: &Ctx, args: &Value) -> Result<Value, String> {
Some(_) => return Err("`mode` must be a string".to_string()),
};
let max_tokens = int_arg(args, "max_tokens", MAX_TOKENS_CAP)?;
+ let evidence = evidence_arg(args)?;
let mut a = AskArgs::new(question);
a.corpus = corpus;
a.mode = mode;
a.max_tokens = max_tokens.map(|n| n as usize);
- Ok(run(ctx, a).await)
+ Ok(run(ctx, a, evidence).await)
}
/// Run the CLI's flow for `a` (never fetching a pack or the catalogue) against
/// this server's node and turn the outcome into a tool result.
-async fn run(ctx: &Ctx, mut a: AskArgs) -> Value {
+async fn run(ctx: &Ctx, mut a: AskArgs, evidence: Option<EvidenceRequest>) -> Value {
a.no_fetch = true;
a.cached_catalogue_only = true;
a.json = false;
@@ -275,7 +325,7 @@ async fn run(ctx: &Ctx, mut a: AskArgs) -> Value {
if let Some(answer) = &outcome.answer {
auto_review(answer, &question);
}
- outcome_result(outcome)
+ outcome_result(outcome, &question, evidence)
}
Err(e) => tool_text(format!("join error: {e}"), true),
}
@@ -313,7 +363,7 @@ const MCP_CORPUS_HINT: &str = "call xerj_hub_ask again with the `corpus` argumen
/// (a miss is an answer, not an error) — carries the Answer JSON as structured
/// content. More than one candidate corpus is not an error either: the text
/// lists them for a re-ask with `corpus`. Anything else is `isError`.
-fn outcome_result(o: AskOutcome) -> Value {
+fn outcome_result(o: AskOutcome, question: &str, evidence: Option<EvidenceRequest>) -> Value {
let mut text = String::new();
for line in &o.stderr {
// The flow's hints name the CLI flag; a tool caller sets an argument.
@@ -322,11 +372,36 @@ fn outcome_result(o: AskOutcome) -> Value {
}
text.push_str(&o.stdout);
match o.answer {
- Some(answer) => json!({
- "content": [ { "type": "text", "text": text } ],
- "structuredContent": answer,
- "isError": false,
- }),
+ Some(answer) => {
+ let receipt = if let Some(request) = evidence {
+ let context = AnswerEvidence {
+ session_id: request.session_id,
+ tool_call_id: request.tool_call_id,
+ question: question.into(),
+ shown_answer: text.clone(),
+ confidence: None,
+ p_min: request.p_min,
+ coverage_gaps: vec!["question-specific coverage not assessed".into()],
+ };
+ // Packs expose rendered index records, not original pinned files.
+ // Never read mutable local files or accept caller-supplied evidence.
+ match answer.evidence_report(context, |_| Ok(None)) {
+ Ok(report) => Some(report),
+ Err(e) => return tool_text(format!("evidence receipt: {e}"), true),
+ }
+ } else {
+ None
+ };
+ let mut result = json!({
+ "content": [ { "type": "text", "text": text } ],
+ "structuredContent": answer,
+ "isError": false,
+ });
+ if let Some(receipt) = receipt {
+ result["structuredContent"]["evidence_receipt"] = json!(receipt);
+ }
+ result
+ }
None => tool_text(text, o.exit != EXIT_NEEDS_DECISION),
}
}
@@ -419,7 +494,7 @@ mod tests {
stderr: vec!["more than one corpus matches; re-run with --corpus <slug>".into()],
answer: None,
};
- let r = outcome_result(ambiguous);
+ let r = outcome_result(ambiguous, "question", None);
assert_eq!(r["isError"], false);
assert!(r["content"][0]["text"].as_str().unwrap().contains("a — x"));
let failed = AskOutcome {
@@ -428,7 +503,7 @@ mod tests {
stderr: vec!["no hub corpus matches; see xerj.org/llms.txt".into()],
answer: None,
};
- assert_eq!(outcome_result(failed)["isError"], true);
+ assert_eq!(outcome_result(failed, "question", None)["isError"], true);
}
/// FTX shell-less trial (2026-10-17): the "nothing matches" and "more than one
@@ -446,12 +521,16 @@ mod tests {
"more than one corpus matches; re-run with --corpus <slug>",
),
] {
- let r = outcome_result(AskOutcome {
- exit,
- stdout: String::new(),
- stderr: vec![line.into()],
- answer: None,
- });
+ let r = outcome_result(
+ AskOutcome {
+ exit,
+ stdout: String::new(),
+ stderr: vec![line.into()],
+ answer: None,
+ },
+ "question",
+ None,
+ );
let text = r["content"][0]["text"].as_str().unwrap();
assert!(!text.contains("--corpus"), "{text}");
assert!(
@@ -460,4 +539,94 @@ mod tests {
);
}
}
+
+ #[test]
+ fn receipt_arguments_are_strict_and_opt_in() {
+ assert!(evidence_arg(&json!({})).unwrap().is_none());
+ for value in [
+ json!(true),
+ json!(null),
+ json!({}),
+ json!({"session_id":"s","tool_call_id":"c","p_min":1.1}),
+ json!({"session_id":"s","tool_call_id":"c","confidence":0.99}),
+ ] {
+ assert!(evidence_arg(&json!({"evidence":value})).is_err());
+ }
+ let request = evidence_arg(&json!({"evidence":{"session_id":"s","tool_call_id":"c"}}))
+ .unwrap()
+ .unwrap();
+ assert_eq!(request.p_min, 0.8);
+ for spec in specs().into_iter().skip(1) {
+ assert_eq!(
+ spec["inputSchema"]["properties"]["evidence"]["type"],
+ "object"
+ );
+ }
+ }
+
+ #[test]
+ fn receipt_is_additive_preserves_default_and_captures_exact_display() {
+ use xerj_common::hub::{Answer, AnswerMode, AnsweredFrom, Hit, LicenceClass};
+ use xerj_common::hub_evidence::TraceEvidenceReport;
+ let mut answer = Answer {
+ corpus: "sample".into(),
+ pin_sha: "a".repeat(40),
+ pin_date: "2026-11-04".into(),
+ age_days: 0,
+ licence_spdx: "MIT".into(),
+ licence_class: LicenceClass::AdaptWithAttribution,
+ answered_from: AnsweredFrom::LocalPack,
+ mode: AnswerMode::How,
+ hits: vec![Hit {
+ file: "src/lib.rs".into(),
+ line: 1,
+ kind: "passage".into(),
+ text: "example".into(),
+ value: None,
+ score: 100.0,
+ licence_warning: None,
+ }],
+ truncated: false,
+ warnings: vec![],
+ };
+ for empty in [false, true] {
+ if empty {
+ answer.hits.clear();
+ }
+ let outcome = || AskOutcome {
+ exit: 0,
+ stdout: xerj_common::hub::render(&answer),
+ stderr: vec!["notice".into()],
+ answer: Some(answer.clone()),
+ };
+ let expected = json!({
+ "content":[{"type":"text","text":format!("notice\n{}",xerj_common::hub::render(&answer))}],
+ "structuredContent":answer,"isError":false,
+ });
+ let default = outcome_result(outcome(), "question", None);
+ assert_eq!(default, expected);
+ let request = EvidenceRequest {
+ session_id: "s".into(),
+ tool_call_id: "c".into(),
+ p_min: 0.8,
+ };
+ let mut opted = outcome_result(outcome(), "question", Some(request));
+ let receipt = opted["structuredContent"]
+ .as_object_mut()
+ .unwrap()
+ .remove("evidence_receipt")
+ .unwrap();
+ assert_eq!(opted, default);
+ let report: TraceEvidenceReport = serde_json::from_value(receipt).unwrap();
+ let entry = &report.entries[0];
+ assert!(entry.abstain && entry.escalate);
+ assert!(entry.confidence.is_none());
+ assert_eq!(
+ entry.shown_answer,
+ default["content"][0]["text"].as_str().unwrap()
+ );
+ TraceEvidenceReport::verify(&report.to_jcs().unwrap(), |_| panic!("no source bytes"))
+ .unwrap();
+ }
+ }
}
diff --git a/engine/crates/xerj-mcp/tests/hub_tools.rs b/engine/crates/xerj-mcp/tests/hub_tools.rs
index 984e0aa0d..997a5f6c5 100644
--- a/engine/crates/xerj-mcp/tests/hub_tools.rs
+++ b/engine/crates/xerj-mcp/tests/hub_tools.rs
@@ -247,7 +247,7 @@ async fn hub_tools_answer_from_a_local_pack_and_never_download() {
for (prop, spec) in props {
let ty = spec["type"].as_str().unwrap_or_default();
assert!(
- ["string", "integer"].contains(&ty),
+ ["string", "integer", "object"].contains(&ty),
"{name}.{prop}: type {ty}"
);
assert!(
@@ -284,6 +284,40 @@ async fn hub_tools_answer_from_a_local_pack_and_never_download() {
);
// The structured content is exactly an Answer (deny_unknown_fields).
let _: xerj_common::hub::Answer = serde_json::from_value(a.clone()).unwrap();
+ let default_answer = a.clone();
+ for (name, args) in [
+ (
+ "xerj_hub_def",
+ json!({
+ "slug": "mini-c", "symbol": "MINI_LIMIT",
+ "evidence": {"session_id": "session-1", "tool_call_id": "def-1"}
+ }),
+ ),
+ (
+ "xerj_hub_ask",
+ json!({
+ "corpus": "mini-c", "question": "MINI_LIMIT",
+ "evidence": {"session_id": "session-1", "tool_call_id": "ask-1"}
+ }),
+ ),
+ ] {
+ let mut opted = call(&url, name, args).await;
+ assert_eq!(opted["isError"], false, "{opted}");
+ let receipt = opted["structuredContent"]
+ .as_object_mut()
+ .unwrap()
+ .remove("evidence_receipt")
+ .unwrap();
+ assert_eq!(opted["structuredContent"], default_answer);
+ let report: xerj_common::hub_evidence::TraceEvidenceReport =
+ serde_json::from_value(receipt).unwrap();
+ assert!(report.entries[0].abstain && report.entries[0].escalate);
+ assert_eq!(report.entries[0].shown_answer, text(&opted));
+ xerj_common::hub_evidence::TraceEvidenceReport::verify(&report.to_jcs().unwrap(), |_| {
+ panic!("no pinned bytes available")
+ })
+ .unwrap();
+ }
// k is carried through.
let r = call(
diff --git a/landing/docs/agents/schemas/mcp-tools.json b/landing/docs/agents/schemas/mcp-tools.json
index 9c93bea26..cc2e7ae06 100644
--- a/landing/docs/agents/schemas/mcp-tools.json
+++ b/landing/docs/agents/schemas/mcp-tools.json
@@ -1016,6 +1016,33 @@
"minimum": 1,
"maximum": 50,
"description": "Max hits to return (default 5)."
+ },
+ "evidence": {
+ "type": "object",
+ "description": "Opt in to structuredContent.evidence_receipt. Supply caller trace identities. Without original pinned bytes and an in-domain calibration assessment, the receipt abstains and escalates; search scores are never probabilities.",
+ "properties": {
+ "session_id": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 512
+ },
+ "tool_call_id": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 512
+ },
+ "p_min": {
+ "type": "number",
+ "minimum": 0,
+ "maximum": 1,
+ "default": 0.8
+ }
+ },
+ "required": [
+ "session_id",
+ "tool_call_id"
+ ],
+ "additionalProperties": false
}
},
"required": [
@@ -1052,6 +1079,33 @@
"minimum": 1,
"maximum": 8192,
"description": "Soft output budget for the rendered answer (about 4 characters a token)."
+ },
+ "evidence": {
+ "type": "object",
+ "description": "Opt in to structuredContent.evidence_receipt. Supply caller trace identities. Without original pinned bytes and an in-domain calibration assessment, the receipt abstains and escalates; search scores are never probabilities.",
+ "properties": {
+ "session_id": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 512
+ },
+ "tool_call_id": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 512
+ },
+ "p_min": {
+ "type": "number",
+ "minimum": 0,
+ "maximum": 1,
+ "default": 0.8
+ }
+ },
+ "required": [
+ "session_id",
+ "tool_call_id"
+ ],
+ "additionalProperties": false
}
},
"required": [