use std::collections::HashMap;
use rmcp::RoleServer;
use rmcp::model::{CallToolResult, ContentBlock, JsonObject, MetaObject};
use rmcp::service::RequestContext;
use crate::idempotency::RequestHash;
use crate::protocol::result_status::{
self, OutcomeClass, PROJECT_EVIDENCE_META_KEY, ProjectEvidence, REPEAT_NOTICE_CONTRACT_VERSION,
REPEAT_NOTICE_META_KEY, RepeatNoticeView,
};
pub const NOTICE_THRESHOLD: u32 = 3;
pub const REPEAT_TRACKER_MAX_ENTRIES: usize = 512;
pub const REPEAT_ELIGIBLE_TOOLS: [&str; 5] = [
"search_symbols",
"search_text",
"get_repo_map",
"find_references",
"find_dependents",
];
const UNBOUND_PROJECT_ID: &str = "unbound";
pub fn is_repeat_eligible(tool: &str) -> bool {
REPEAT_ELIGIBLE_TOOLS.contains(&tool)
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum TransportLane {
Stdio,
#[default]
Shared,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum SessionDiscriminator {
Stdio,
HttpInert,
}
impl SessionDiscriminator {
pub fn observe(declared: TransportLane, context: &RequestContext<RoleServer>) -> LaneWitness {
Self::from_observations(
declared,
context
.extensions
.get::<axum::http::request::Parts>()
.is_some(),
)
}
fn from_observations(declared: TransportLane, http_parts_present: bool) -> LaneWitness {
LaneWitness(match (declared, http_parts_present) {
(TransportLane::Stdio, false) => Self::Stdio,
_ => Self::HttpInert,
})
}
}
#[derive(Debug, Clone, Copy)]
pub struct LaneWitness(SessionDiscriminator);
impl LaneWitness {
#[cfg(test)]
pub(crate) fn assume(lane: SessionDiscriminator) -> Self {
Self(lane)
}
#[cfg(test)]
fn lane(&self) -> SessionDiscriminator {
self.0
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct TrackerEpoch(u64);
impl TrackerEpoch {
#[cfg(test)]
pub(crate) const fn assume(epoch: u64) -> Self {
Self(epoch)
}
}
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct RepeatKey {
session: SessionDiscriminator,
epoch: TrackerEpoch,
tool: String,
request_hash: RequestHash,
}
impl RepeatKey {
pub fn observe(
lane: LaneWitness,
epoch: TrackerEpoch,
tool: &str,
arguments: Option<&JsonObject>,
) -> Option<Self> {
let session = lane.0;
if session != SessionDiscriminator::Stdio || !is_repeat_eligible(tool) {
return None;
}
if arguments
.and_then(|arguments| arguments.get("projects"))
.is_some_and(|projects| !projects.is_null())
{
return None;
}
let args = serde_json::Value::Object(arguments.cloned().unwrap_or_default());
let request_hash = RequestHash::for_tool_request(tool, &args).ok()?;
Some(Self {
session,
epoch,
tool: tool.to_string(),
request_hash,
})
}
pub fn tool(&self) -> &str {
&self.tool
}
pub fn request_hash(&self) -> &RequestHash {
&self.request_hash
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct BodyDigest([u8; 32]);
impl BodyDigest {
fn of_content(content: &[ContentBlock]) -> Self {
let mut frame = Vec::new();
for block in content {
if let ContentBlock::Text(text) = block {
frame.extend_from_slice(&(text.text.len() as u64).to_le_bytes());
frame.extend_from_slice(text.text.as_bytes());
}
}
Self(crate::hash::digest(&frame))
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ObservedServe {
evidence: ProjectEvidence,
body_digest: BodyDigest,
}
impl ObservedServe {
#[cfg(test)]
pub(crate) fn for_test(evidence: ProjectEvidence, content: &[ContentBlock]) -> Self {
Self {
evidence,
body_digest: BodyDigest::of_content(content),
}
}
}
#[derive(Debug)]
pub struct RepeatWitness {
generation: u64,
}
impl RepeatWitness {
fn observe(prior: &ObservedServe, current: &ObservedServe) -> Option<Self> {
(prior == current).then_some(Self {
generation: current.evidence.generation,
})
}
pub fn evidence_generation(&self) -> u64 {
self.generation
}
}
#[derive(Debug)]
pub struct RepeatNotice {
witness: RepeatWitness,
repeat_count: u32,
tool: String,
request_hash: RequestHash,
}
impl RepeatNotice {
fn new(witness: RepeatWitness, repeat_count: u32, key: &RepeatKey) -> Option<Self> {
(repeat_count >= NOTICE_THRESHOLD).then(|| Self {
witness,
repeat_count,
tool: key.tool().to_string(),
request_hash: key.request_hash().clone(),
})
}
pub fn repeat_count(&self) -> u32 {
self.repeat_count
}
pub fn evidence_generation(&self) -> u64 {
self.witness.evidence_generation()
}
pub fn text(&self) -> String {
format!(
"Repeat notice: identical request served {}x. Across these serves, no index change was published and the response text before this notice was unchanged. Retrying it unchanged has not produced new information.",
self.repeat_count
)
}
pub fn view(&self) -> RepeatNoticeView {
RepeatNoticeView {
contract_version: REPEAT_NOTICE_CONTRACT_VERSION,
repeat_count: self.repeat_count(),
tool: self.tool.clone(),
request_hash: self.request_hash.as_str().to_string(),
evidence_generation: self.evidence_generation(),
}
}
pub fn attach(&self, result: &mut CallToolResult) {
let text = self.text();
match result
.content
.iter()
.rposition(|block| matches!(block, ContentBlock::Text(_)))
{
Some(index) => {
if let ContentBlock::Text(block) = &mut result.content[index] {
block.text.push_str("\n\n");
block.text.push_str(&text);
}
}
None => result.content.push(ContentBlock::text(text)),
}
let meta = result
.meta
.get_or_insert_with(|| MetaObject(JsonObject::new()));
meta.0.insert(
REPEAT_NOTICE_META_KEY.to_string(),
serde_json::to_value(self.view()).expect("RepeatNoticeView must serialize to JSON"),
);
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum UnobservedReason {
EvidenceUnavailable,
ProjectUnbound,
InternalFailure,
ErrorWithoutOutcomeClass,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ServeObservation(Observation);
#[derive(Debug, Clone, PartialEq, Eq)]
enum Observation {
Observed(ObservedServe),
Unobserved(UnobservedReason),
}
impl ServeObservation {
#[cfg(test)]
pub(crate) fn observed_for_test(serve: ObservedServe) -> Self {
Self(Observation::Observed(serve))
}
#[cfg(test)]
fn observed_serve(&self) -> Option<&ObservedServe> {
match &self.0 {
Observation::Observed(serve) => Some(serve),
Observation::Unobserved(_) => None,
}
}
#[cfg(test)]
fn unobserved_reason(&self) -> Option<UnobservedReason> {
match &self.0 {
Observation::Observed(_) => None,
Observation::Unobserved(reason) => Some(*reason),
}
}
pub fn from_result(result: &CallToolResult) -> Self {
let meta = result.meta.as_ref();
let Some(evidence) = meta
.and_then(|meta| meta.0.get(PROJECT_EVIDENCE_META_KEY))
.and_then(|value| serde_json::from_value::<ProjectEvidence>(value.clone()).ok())
else {
return Self(Observation::Unobserved(
UnobservedReason::EvidenceUnavailable,
));
};
if evidence.project_id == UNBOUND_PROJECT_ID {
return Self(Observation::Unobserved(UnobservedReason::ProjectUnbound));
}
let observed = || ObservedServe {
evidence: evidence.clone(),
body_digest: BodyDigest::of_content(&result.content),
};
Self(match result_status::observed_outcome_class(meta) {
Some(OutcomeClass::InternalFailure) => {
Observation::Unobserved(UnobservedReason::InternalFailure)
}
Some(_) => Observation::Observed(observed()),
None if result.is_error == Some(true) => {
Observation::Unobserved(UnobservedReason::ErrorWithoutOutcomeClass)
}
None => Observation::Observed(observed()),
})
}
}
#[derive(Debug)]
struct RepeatRun {
count: u32,
observed: ObservedServe,
}
#[derive(Debug, Default)]
pub struct RepeatTracker {
runs: HashMap<RepeatKey, RepeatRun>,
epoch: u64,
}
impl RepeatTracker {
pub fn epoch(&self) -> TrackerEpoch {
TrackerEpoch(self.epoch)
}
pub fn record_serve(
&mut self,
key: RepeatKey,
observation: ServeObservation,
) -> Option<RepeatNotice> {
if key.epoch != self.epoch() {
return None;
}
let current = match observation.0 {
Observation::Observed(current) => current,
Observation::Unobserved(_) => {
self.runs.remove(&key);
return None;
}
};
if let Some(run) = self.runs.get_mut(&key) {
return match RepeatWitness::observe(&run.observed, ¤t) {
Some(witness) => {
run.count = run.count.saturating_add(1);
RepeatNotice::new(witness, run.count, &key)
}
None => {
run.observed = current;
run.count = 1;
None
}
};
}
if self.runs.len() >= REPEAT_TRACKER_MAX_ENTRIES {
self.runs.clear();
}
self.runs.insert(
key,
RepeatRun {
count: 1,
observed: current,
},
);
None
}
pub(crate) fn clear(&mut self) {
self.runs.clear();
self.epoch = self.epoch.wrapping_add(1);
}
#[cfg(test)]
pub fn len(&self) -> usize {
self.runs.len()
}
#[cfg(test)]
pub fn is_empty(&self) -> bool {
self.runs.is_empty()
}
#[cfg(test)]
fn count_of(&self, key: &RepeatKey) -> Option<u32> {
self.runs.get(key).map(|run| run.count)
}
#[cfg(test)]
fn set_count_for_test(&mut self, key: &RepeatKey, count: u32) {
if let Some(run) = self.runs.get_mut(key) {
run.count = count;
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::protocol::result_status::{
OutcomeClass, PROJECT_EVIDENCE_META_KEY, ProjectEvidence, REPEAT_NOTICE_META_KEY,
RESULT_STATUS_META_KEY, ResultStatus,
};
use rmcp::model::{CallToolResult, ContentBlock, JsonObject, MetaObject};
use serde_json::json;
fn evidence(generation: u64) -> ProjectEvidence {
ProjectEvidence {
project_id: "project-v1-repeat".to_string(),
project_name: "repeat".to_string(),
canonical_root: Some("C:/work/repeat".to_string()),
generation,
index_state: "Ready".to_string(),
load_source: "memory".to_string(),
index_files: 3,
index_symbols: 4,
}
}
fn args(value: serde_json::Value) -> JsonObject {
serde_json::from_value(value).expect("object arguments")
}
fn stdio() -> LaneWitness {
LaneWitness::assume(SessionDiscriminator::Stdio)
}
fn epoch0() -> TrackerEpoch {
TrackerEpoch::assume(0)
}
fn key(tool: &str, query: &str) -> RepeatKey {
RepeatKey::observe(
stdio(),
epoch0(),
tool,
Some(&args(json!({ "query": query }))),
)
.expect("an eligible stdio call keys the tracker")
}
fn result_with(
evidence_value: serde_json::Value,
status: Option<serde_json::Value>,
is_error: Option<bool>,
) -> CallToolResult {
let mut meta = JsonObject::new();
meta.insert(PROJECT_EVIDENCE_META_KEY.to_string(), evidence_value);
if let Some(status) = status {
meta.insert(RESULT_STATUS_META_KEY.to_string(), status);
}
let mut result = CallToolResult::success(vec![ContentBlock::text("body")]);
result.is_error = is_error;
result.with_meta(Some(MetaObject(meta)))
}
fn status_value(outcome: OutcomeClass) -> serde_json::Value {
serde_json::to_value(ResultStatus::new(outcome)).expect("status serializes")
}
fn body() -> BodyDigest {
BodyDigest::of_content(&[ContentBlock::text("body")])
}
fn observed_serve(generation: u64) -> ObservedServe {
ObservedServe {
evidence: evidence(generation),
body_digest: body(),
}
}
fn observed(generation: u64) -> ServeObservation {
ServeObservation::observed_for_test(observed_serve(generation))
}
fn serve_equal(
tracker: &mut RepeatTracker,
key: &RepeatKey,
generation: u64,
n: u32,
) -> Option<RepeatNotice> {
let mut last = None;
for _ in 0..n {
last = tracker.record_serve(key.clone(), observed(generation));
}
last
}
#[test]
fn eligible_list_is_pinned() {
assert_eq!(
REPEAT_ELIGIBLE_TOOLS,
[
"search_symbols",
"search_text",
"get_repo_map",
"find_references",
"find_dependents",
]
);
for tool in REPEAT_ELIGIBLE_TOOLS {
assert!(is_repeat_eligible(tool), "{tool} must be eligible");
assert!(
RepeatKey::observe(stdio(), epoch0(), tool, None).is_some(),
"{tool} must key the tracker on stdio"
);
}
for tool in [
"get_symbol",
"search_files",
"get_file_content",
"status",
"what_changed",
"symforge",
"symforge_edit",
"index_folder",
] {
assert!(!is_repeat_eligible(tool), "{tool} must stay ineligible");
assert!(
RepeatKey::observe(stdio(), epoch0(), tool, None).is_none(),
"{tool} must never key the tracker"
);
}
assert_eq!(NOTICE_THRESHOLD, 3);
assert_eq!(REPEAT_TRACKER_MAX_ENTRIES, 512);
}
#[test]
fn witness_requires_full_equality() {
let prior = observed_serve(7);
let with = |evidence: ProjectEvidence| ObservedServe {
evidence,
body_digest: body(),
};
assert!(
RepeatWitness::observe(&prior, &observed_serve(7)).is_some(),
"equal evidence and body must be witnessable"
);
assert!(RepeatWitness::observe(&prior, &observed_serve(8)).is_none());
let mut files = evidence(7);
files.index_files += 1;
assert!(RepeatWitness::observe(&prior, &with(files)).is_none());
let mut state = evidence(7);
state.index_state = "Loading".to_string();
assert!(RepeatWitness::observe(&prior, &with(state)).is_none());
let mut root = evidence(7);
root.canonical_root = None;
assert!(RepeatWitness::observe(&prior, &with(root)).is_none());
let mut source = evidence(7);
source.load_source = "snapshot".to_string();
assert!(RepeatWitness::observe(&prior, &with(source)).is_none());
let mut symbols = evidence(7);
symbols.index_symbols += 1;
assert!(RepeatWitness::observe(&prior, &with(symbols)).is_none());
let mut id = evidence(7);
id.project_id.push('x');
assert!(RepeatWitness::observe(&prior, &with(id)).is_none());
let mut name = evidence(7);
name.project_name.push('x');
assert!(RepeatWitness::observe(&prior, &with(name)).is_none());
let other_body = ObservedServe {
evidence: evidence(7),
body_digest: BodyDigest::of_content(&[ContentBlock::text("body\n\ndiagnostic")]),
};
assert!(RepeatWitness::observe(&prior, &other_body).is_none());
assert_eq!(
RepeatWitness::observe(&prior, &observed_serve(7))
.expect("witness")
.evidence_generation(),
7
);
}
#[test]
fn notice_threshold_is_three_and_count_saturates() {
let witness =
|| RepeatWitness::observe(&observed_serve(1), &observed_serve(1)).expect("witness");
let k = key("search_symbols", "anchor");
assert!(
RepeatNotice::new(witness(), 2, &k).is_none(),
"count 2 is below the threshold"
);
let notice = RepeatNotice::new(witness(), 3, &k).expect("count 3 notices");
assert_eq!(notice.repeat_count(), 3);
assert_eq!(notice.evidence_generation(), 1);
assert_eq!(
notice.text(),
"Repeat notice: identical request served 3x. Across these serves, no index change was published and the response text before this notice was unchanged. Retrying it unchanged has not produced new information."
);
let mut tracker = RepeatTracker::default();
assert!(
serve_equal(&mut tracker, &k, 1, 2).is_none(),
"serve 2: no notice"
);
assert_eq!(tracker.count_of(&k), Some(2));
let third = serve_equal(&mut tracker, &k, 1, 1).expect("serve 3 notices");
assert_eq!(third.repeat_count(), 3);
let fourth = serve_equal(&mut tracker, &k, 1, 1).expect("serve 4 notices");
assert_eq!(fourth.repeat_count(), 4);
tracker.set_count_for_test(&k, u32::MAX);
let saturated = serve_equal(&mut tracker, &k, 1, 1).expect("saturated serve notices");
assert_eq!(
saturated.repeat_count(),
u32::MAX,
"count saturates, never wraps"
);
assert_eq!(tracker.count_of(&k), Some(u32::MAX));
}
#[test]
fn unobserved_evidence_clears_run() {
let full = serde_json::to_value(evidence(5)).expect("evidence serializes");
let marker = json!({ "bound": false, "reason": "project_evidence_unavailable" });
let garbage = json!("not evidence");
let mut unbound_evidence = evidence(5);
unbound_evidence.project_id = "unbound".to_string();
let unbound = serde_json::to_value(&unbound_evidence).expect("serializes");
assert_eq!(
ServeObservation::from_result(&result_with(full.clone(), None, None)).observed_serve(),
Some(&observed_serve(5))
);
assert_eq!(
ServeObservation::from_result(&result_with(marker.clone(), None, None))
.unobserved_reason(),
Some(UnobservedReason::EvidenceUnavailable)
);
assert_eq!(
ServeObservation::from_result(&result_with(garbage.clone(), None, None))
.unobserved_reason(),
Some(UnobservedReason::EvidenceUnavailable)
);
assert_eq!(
ServeObservation::from_result(&result_with(unbound.clone(), None, None))
.unobserved_reason(),
Some(UnobservedReason::ProjectUnbound)
);
let bare = CallToolResult::success(vec![ContentBlock::text("body")]);
assert_eq!(
ServeObservation::from_result(&bare).unobserved_reason(),
Some(UnobservedReason::EvidenceUnavailable)
);
for (label, unobserved) in [
("bound:false marker", marker),
("non-deserializable value", garbage),
("unbound project_id", unbound),
] {
let mut tracker = RepeatTracker::default();
let k = key("search_symbols", "anchor");
assert!(serve_equal(&mut tracker, &k, 5, 2).is_none());
assert_eq!(tracker.count_of(&k), Some(2), "{label}: run reached 2");
let observation = ServeObservation::from_result(&result_with(unobserved, None, None));
assert!(
tracker.record_serve(k.clone(), observation).is_none(),
"{label}: an unobserved serve never notices"
);
assert_eq!(tracker.count_of(&k), None, "{label}: the run is cleared");
for _ in 0..2 {
let observation = ServeObservation::from_result(&result_with(
json!({ "bound": false, "reason": "project_evidence_unavailable" }),
None,
None,
));
assert!(tracker.record_serve(k.clone(), observation).is_none());
}
assert_eq!(tracker.count_of(&k), None, "{label}: still nothing");
assert!(
serve_equal(&mut tracker, &k, 5, 2).is_none(),
"{label}: 1, 2"
);
let third = serve_equal(&mut tracker, &k, 5, 1).expect("{label}: 3 notices");
assert_eq!(third.repeat_count(), 3);
}
let mut tracker = RepeatTracker::default();
let k = key("search_symbols", "anchor");
let mut last = None;
for _ in 0..3 {
last = tracker.record_serve(
k.clone(),
ServeObservation::from_result(&result_with(full.clone(), None, None)),
);
}
assert_eq!(last.expect("control notices").repeat_count(), 3);
}
#[test]
fn internal_failure_clears_run() {
let full = serde_json::to_value(evidence(9)).expect("evidence serializes");
let mut tracker = RepeatTracker::default();
let k = key("find_references", "anchor");
assert!(serve_equal(&mut tracker, &k, 9, 2).is_none());
let failure = result_with(
full.clone(),
Some(status_value(OutcomeClass::InternalFailure)),
Some(true),
);
assert_eq!(
ServeObservation::from_result(&failure).unobserved_reason(),
Some(UnobservedReason::InternalFailure)
);
assert!(
tracker
.record_serve(k.clone(), ServeObservation::from_result(&failure))
.is_none()
);
assert_eq!(tracker.count_of(&k), None, "InternalFailure clears the run");
assert!(serve_equal(&mut tracker, &k, 9, 2).is_none());
let invalid = result_with(
full.clone(),
Some(status_value(OutcomeClass::InvalidRequest)),
Some(true),
);
let notice = tracker
.record_serve(k.clone(), ServeObservation::from_result(&invalid))
.expect("InvalidRequest advances to the notice");
assert_eq!(notice.repeat_count(), 3);
for outcome in [OutcomeClass::NotFound, OutcomeClass::EmptyResult] {
let serve = result_with(full.clone(), Some(status_value(outcome)), None);
let notice = tracker
.record_serve(k.clone(), ServeObservation::from_result(&serve))
.expect("non-internal outcomes advance");
assert!(notice.repeat_count() >= 4);
}
let mut tracker = RepeatTracker::default();
assert!(serve_equal(&mut tracker, &k, 9, 2).is_none());
let plain_error = result_with(full.clone(), None, Some(true));
assert_eq!(
ServeObservation::from_result(&plain_error).unobserved_reason(),
Some(UnobservedReason::ErrorWithoutOutcomeClass)
);
assert!(
tracker
.record_serve(k.clone(), ServeObservation::from_result(&plain_error))
.is_none()
);
assert_eq!(tracker.count_of(&k), None);
assert!(serve_equal(&mut tracker, &k, 9, 2).is_none());
let plain_ok = result_with(full, None, Some(false));
let notice = tracker
.record_serve(k.clone(), ServeObservation::from_result(&plain_ok))
.expect("a plain non-error serve advances");
assert_eq!(notice.repeat_count(), 3);
}
#[test]
fn tracker_cap_clears_without_false_claim() {
let mut tracker = RepeatTracker::default();
let k0 = key("search_text", "k0");
assert!(serve_equal(&mut tracker, &k0, 1, 2).is_none());
assert_eq!(tracker.count_of(&k0), Some(2));
for i in 1..REPEAT_TRACKER_MAX_ENTRIES {
let k = key("search_text", &format!("k{i}"));
assert!(tracker.record_serve(k, observed(1)).is_none());
}
assert_eq!(
tracker.len(),
REPEAT_TRACKER_MAX_ENTRIES,
"map is exactly at cap"
);
assert!(!tracker.is_empty());
assert_eq!(tracker.count_of(&k0), Some(2), "k0 survives up to the cap");
let overflow = key("search_text", "overflow");
assert!(
tracker
.record_serve(overflow.clone(), observed(1))
.is_none()
);
assert_eq!(tracker.len(), 1, "cap clear leaves only the new key");
assert_eq!(tracker.count_of(&overflow), Some(1));
assert_eq!(tracker.count_of(&k0), None, "k0's run is gone");
assert!(serve_equal(&mut tracker, &k0, 1, 1).is_none());
assert_eq!(tracker.count_of(&k0), Some(1));
assert!(serve_equal(&mut tracker, &k0, 1, 1).is_none());
let notice = serve_equal(&mut tracker, &k0, 1, 1).expect("re-accumulated to 3");
assert_eq!(notice.repeat_count(), 3);
}
#[test]
fn clear_restarts_runs_at_one() {
let mut tracker = RepeatTracker::default();
let k = key("search_symbols", "anchor");
assert!(serve_equal(&mut tracker, &k, 1, 2).is_none());
assert_eq!(tracker.count_of(&k), Some(2));
tracker.clear();
assert!(tracker.is_empty(), "clear() drops every run");
let k = RepeatKey::observe(
stdio(),
tracker.epoch(),
"search_symbols",
Some(&args(json!({ "query": "anchor" }))),
)
.expect("the same call, keyed against the new incarnation");
assert!(
serve_equal(&mut tracker, &k, 1, 1).is_none(),
"count 1 after clear"
);
assert_eq!(tracker.count_of(&k), Some(1));
assert!(serve_equal(&mut tracker, &k, 1, 1).is_none(), "count 2");
let notice = serve_equal(&mut tracker, &k, 1, 1).expect("count 3 notices again");
assert_eq!(notice.repeat_count(), 3);
}
#[test]
fn serve_observed_before_a_clear_never_joins_a_run() {
let mint = |tracker: &RepeatTracker| {
RepeatKey::observe(
stdio(),
tracker.epoch(),
"search_symbols",
Some(&args(json!({ "query": "anchor" }))),
)
.expect("an eligible stdio call keys the tracker")
};
let mut tracker = RepeatTracker::default();
let stale = mint(&tracker);
assert!(serve_equal(&mut tracker, &stale, 1, 2).is_none());
assert_eq!(tracker.count_of(&stale), Some(2));
tracker.clear();
assert_eq!(tracker.len(), 0, "the clear dropped the run");
for serve in 1..=3 {
assert!(
tracker.record_serve(stale.clone(), observed(1)).is_none(),
"serve {serve} of a pre-clear key must never notice"
);
assert_eq!(
tracker.len(),
0,
"serve {serve} of a pre-clear key must not be recorded at all"
);
}
let fresh = mint(&tracker);
assert_ne!(
fresh, stale,
"the epoch is part of the key, so a re-minted key is a different key"
);
assert!(tracker.record_serve(fresh.clone(), observed(1)).is_none());
assert!(tracker.record_serve(fresh.clone(), observed(1)).is_none());
let notice = tracker
.record_serve(fresh.clone(), observed(1))
.expect("a post-clear key notices at 3");
assert_eq!(notice.repeat_count(), 3);
assert_eq!(tracker.len(), 1);
assert!(tracker.record_serve(stale, observed(1)).is_none());
assert_eq!(tracker.len(), 1, "the stale serve added nothing");
assert_eq!(tracker.count_of(&fresh), Some(3), "and disturbed nothing");
}
#[test]
fn only_a_declared_stdio_transport_ever_accumulates() {
assert_eq!(TransportLane::default(), TransportLane::Shared);
for http_parts_present in [false, true] {
let witness =
SessionDiscriminator::from_observations(TransportLane::Shared, http_parts_present);
assert_eq!(
witness.lane(),
SessionDiscriminator::HttpInert,
"an undeclared lane is inert (http_parts_present={http_parts_present})"
);
assert!(
RepeatKey::observe(witness, epoch0(), "search_symbols", None).is_none(),
"an undeclared lane must never key the tracker \
(http_parts_present={http_parts_present})"
);
}
let contradicted = SessionDiscriminator::from_observations(TransportLane::Stdio, true);
assert_eq!(contradicted.lane(), SessionDiscriminator::HttpInert);
assert!(RepeatKey::observe(contradicted, epoch0(), "search_symbols", None).is_none());
let declared = SessionDiscriminator::from_observations(TransportLane::Stdio, false);
assert_eq!(declared.lane(), SessionDiscriminator::Stdio);
let k = RepeatKey::observe(
declared,
epoch0(),
"search_symbols",
Some(&args(json!({ "query": "anchor" }))),
)
.expect("a declared stdio lane keys the tracker");
let mut tracker = RepeatTracker::default();
assert!(serve_equal(&mut tracker, &k, 1, 2).is_none());
let notice = serve_equal(&mut tracker, &k, 1, 1).expect("declared stdio notices at 3");
assert_eq!(notice.repeat_count(), 3);
}
#[test]
fn http_inert_lane_and_projects_fan_out_never_key() {
let single = args(json!({ "query": "anchor" }));
assert!(
RepeatKey::observe(
LaneWitness::assume(SessionDiscriminator::HttpInert),
epoch0(),
"search_symbols",
Some(&single)
)
.is_none(),
"no observable session identity => no key"
);
let fan_out = args(json!({ "query": "anchor", "projects": ["*"] }));
assert!(
RepeatKey::observe(stdio(), epoch0(), "search_symbols", Some(&fan_out)).is_none(),
"a set-valued projects fan-out never keys"
);
let null_projects = args(json!({ "query": "anchor", "projects": null }));
let keyed = RepeatKey::observe(stdio(), epoch0(), "search_symbols", Some(&null_projects))
.expect("projects:null is absence");
let control = RepeatKey::observe(stdio(), epoch0(), "search_symbols", Some(&single))
.expect("stdio single-project keys");
assert_eq!(control.tool(), "search_symbols");
assert_eq!(
control,
RepeatKey::observe(stdio(), epoch0(), "search_symbols", Some(&single)).expect("same")
);
assert_ne!(
control, keyed,
"an explicit null field changes the canonical JSON"
);
let other = args(json!({ "query": "other" }));
assert_ne!(
control,
RepeatKey::observe(stdio(), epoch0(), "search_symbols", Some(&other)).expect("other")
);
let empty = args(json!({}));
assert_eq!(
RepeatKey::observe(stdio(), epoch0(), "get_repo_map", None).expect("none"),
RepeatKey::observe(stdio(), epoch0(), "get_repo_map", Some(&empty)).expect("empty")
);
}
#[test]
fn body_change_with_equal_evidence_replaces_run() {
let full = serde_json::to_value(evidence(3)).expect("evidence serializes");
let serve = |blocks: &[&str]| {
let mut result = result_with(full.clone(), None, None);
result.content = blocks
.iter()
.map(|text| ContentBlock::text(*text))
.collect();
ServeObservation::from_result(&result)
};
let k = key("search_text", "needle-zz");
let mut tracker = RepeatTracker::default();
assert!(
tracker
.record_serve(k.clone(), serve(&["no matches"]))
.is_none()
);
assert!(
tracker
.record_serve(k.clone(), serve(&["no matches"]))
.is_none()
);
assert_eq!(tracker.count_of(&k), Some(2));
assert!(
tracker
.record_serve(
k.clone(),
serve(&["no matches\n\nuntracked file may match: 1 untracked path(s)"]),
)
.is_none(),
"a changed body under equal evidence must never notice"
);
assert_eq!(
tracker.count_of(&k),
Some(1),
"the run restarts at 1 on the new body"
);
assert!(
tracker
.record_serve(k.clone(), serve(&["ab", "c"]))
.is_none()
);
assert_eq!(tracker.count_of(&k), Some(1));
assert!(
tracker
.record_serve(k.clone(), serve(&["a", "bc"]))
.is_none()
);
assert_eq!(tracker.count_of(&k), Some(1), "framing differs => restart");
let mut tracker = RepeatTracker::default();
assert!(
tracker
.record_serve(k.clone(), serve(&["no matches"]))
.is_none()
);
assert!(
tracker
.record_serve(k.clone(), serve(&["no matches"]))
.is_none()
);
let notice = tracker
.record_serve(k.clone(), serve(&["no matches"]))
.expect("an unchanged body under equal evidence notices");
assert_eq!(notice.repeat_count(), 3);
}
#[test]
fn notice_attaches_to_final_text_block_and_meta() {
let k = key("get_repo_map", "anchor");
let witness =
RepeatWitness::observe(&observed_serve(4), &observed_serve(4)).expect("witness");
let notice = RepeatNotice::new(witness, 3, &k).expect("notice");
let mut result = CallToolResult::success(vec![
ContentBlock::text("first"),
ContentBlock::text("second"),
]);
result.is_error = Some(true);
let before_meta = result.meta.clone();
notice.attach(&mut result);
assert_eq!(result.is_error, Some(true), "isError untouched");
assert_eq!(
result.content.len(),
2,
"no block added when a text block exists"
);
assert_eq!(result.content[0].as_text().expect("text").text, "first");
assert_eq!(
result.content[1].as_text().expect("text").text,
format!("second\n\n{}", notice.text())
);
let meta = result.meta.as_ref().expect("meta created");
assert!(before_meta.is_none());
let view = meta.0.get(REPEAT_NOTICE_META_KEY).expect("meta carrier");
assert_eq!(
view,
&json!({
"contract_version": 2,
"repeat_count": 3,
"tool": "get_repo_map",
"request_hash": k.request_hash().as_str(),
"evidence_generation": 4,
})
);
let mut empty = CallToolResult::success(vec![]);
notice.attach(&mut empty);
assert_eq!(empty.content.len(), 1);
assert_eq!(
empty.content[0].as_text().expect("text").text,
notice.text()
);
assert!(
empty
.meta
.as_ref()
.is_some_and(|m| m.0.contains_key(REPEAT_NOTICE_META_KEY))
);
}
}