use serde::{Deserialize, Serialize};
pub const FEATURE_VERSION: u32 = 3;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum TaskKind {
CodeEdit,
TestGen,
Explore,
Review,
Extract,
Chat,
#[default]
Other,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct TrajectorySignals {
pub tool_errors: u32,
pub tool_results: u32,
pub assistant_turns: u32,
pub repeated_tool_calls: u32,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Default)]
#[repr(u8)]
pub enum DifficultyHint {
#[default]
None = 0,
Low = 1,
Medium = 2,
High = 3,
}
impl DifficultyHint {
#[must_use]
pub fn score(s: TrajectorySignals) -> Self {
if s.tool_results == 0 && s.repeated_tool_calls == 0 {
return Self::None;
}
let e = s.tool_errors;
let n = s.tool_results;
let half_failing = n > 0 && e > n / 2;
let any_failing = e > 0;
let stuck = s.repeated_tool_calls >= 2;
let deep = s.assistant_turns >= 5;
match (half_failing || stuck, any_failing, deep) {
(true, _, true) => Self::High,
(true, _, false) => Self::Medium,
(false, true, true) => Self::Medium,
(false, true, false) => Self::Low,
(false, false, _) => Self::Low,
}
}
#[must_use]
pub const fn as_u8(self) -> u8 {
self as u8
}
}
#[expect(
clippy::trivially_copy_pass_by_ref,
reason = "serde's skip_serializing_if requires a &T predicate"
)]
fn is_no_signal(hint: &u8) -> bool {
*hint == DifficultyHint::None as u8
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Features {
pub version: u32,
pub task_kind: TaskKind,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub language: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub agent: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub subagent: Option<String>,
pub prompt_token_bucket: u32,
pub tool_count: u32,
pub has_images: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub repo_fingerprint: Option<String>,
pub session_failure_count: u32,
#[serde(default, skip_serializing_if = "is_no_signal")]
pub difficulty_hint: u8,
pub hour_bucket: u8,
}
impl Features {
#[must_use]
pub fn new(task_kind: TaskKind) -> Self {
Self {
version: FEATURE_VERSION,
task_kind,
language: None,
agent: None,
subagent: None,
prompt_token_bucket: 0,
tool_count: 0,
has_images: false,
repo_fingerprint: None,
session_failure_count: 0,
difficulty_hint: DifficultyHint::None as u8,
hour_bucket: 0,
}
}
}
#[must_use]
pub fn token_bucket(n: u64) -> u32 {
if n < 2 {
0
} else {
63 - n.leading_zeros()
}
}
#[must_use]
pub fn repo_fingerprint(salt: &str, repo: &str) -> String {
use sha2::{Digest, Sha256};
let mut h = Sha256::new();
h.update(salt.as_bytes());
h.update([0u8]); h.update(repo.as_bytes());
let digest = h.finalize();
hex::encode(&digest[..8]) }
#[must_use]
pub fn hour_bucket(ts: jiff::Timestamp) -> u8 {
ts.to_zoned(jiff::tz::TimeZone::UTC).hour() as u8
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn absent_tool_activity_is_no_signal_not_a_good_signal() {
assert_eq!(
DifficultyHint::score(TrajectorySignals::default()),
DifficultyHint::None
);
assert_eq!(
DifficultyHint::score(TrajectorySignals {
assistant_turns: 50,
..Default::default()
}),
DifficultyHint::None
);
}
#[test]
fn a_failing_window_outranks_a_clean_one() {
let clean = DifficultyHint::score(TrajectorySignals {
tool_results: 6,
tool_errors: 0,
assistant_turns: 4,
repeated_tool_calls: 0,
});
let failing = DifficultyHint::score(TrajectorySignals {
tool_results: 6,
tool_errors: 5,
assistant_turns: 4,
repeated_tool_calls: 0,
});
assert_eq!(clean, DifficultyHint::Low);
assert!(
failing > clean,
"5-of-6 failing must outrank 0-of-6: {failing:?} vs {clean:?}"
);
}
#[test]
fn repetition_is_a_stuck_signal_without_any_errors() {
let hint = DifficultyHint::score(TrajectorySignals {
tool_results: 4,
tool_errors: 0,
assistant_turns: 5,
repeated_tool_calls: 3,
});
assert!(
hint >= DifficultyHint::Medium,
"3 repeated calls with no errors must still read as difficulty, got {hint:?}"
);
}
#[test]
fn sustained_failure_deep_in_a_session_is_the_top_bucket() {
let deep = DifficultyHint::score(TrajectorySignals {
tool_results: 10,
tool_errors: 8,
assistant_turns: 12,
repeated_tool_calls: 2,
});
let shallow = DifficultyHint::score(TrajectorySignals {
tool_results: 10,
tool_errors: 8,
assistant_turns: 2,
repeated_tool_calls: 0,
});
assert_eq!(deep, DifficultyHint::High);
assert!(
shallow < deep,
"the same failure rate early must not score as high as late: {shallow:?} vs {deep:?}"
);
}
#[test]
fn extreme_counts_do_not_overflow() {
let h = DifficultyHint::score(TrajectorySignals {
tool_errors: u32::MAX,
tool_results: u32::MAX,
assistant_turns: u32::MAX,
repeated_tool_calls: u32::MAX,
});
assert_eq!(h, DifficultyHint::High, "all-failing at any scale is High");
assert!(
DifficultyHint::score(TrajectorySignals {
tool_errors: 3,
tool_results: 5,
..Default::default()
}) >= DifficultyHint::Medium
);
assert_eq!(
DifficultyHint::score(TrajectorySignals {
tool_errors: 2,
tool_results: 5,
..Default::default()
}),
DifficultyHint::Low,
"2 of 5 is not a majority and must stay Low"
);
}
#[test]
fn the_hint_is_always_within_its_declared_range() {
for tool_results in 0..12u32 {
for tool_errors in 0..=tool_results {
for assistant_turns in [0u32, 1, 7, 8, 40] {
for repeated_tool_calls in 0..4u32 {
let h = DifficultyHint::score(TrajectorySignals {
tool_errors,
tool_results,
assistant_turns,
repeated_tool_calls,
});
assert!(h.as_u8() <= DifficultyHint::High.as_u8());
}
}
}
}
}
#[test]
fn a_v1_trace_without_the_hint_still_deserializes() {
let v1 = r#"{"version":1,"task_kind":"other","prompt_token_bucket":3,
"tool_count":0,"has_images":false,"session_failure_count":0,"hour_bucket":9}"#;
let f: Features = serde_json::from_str(v1).expect("a v1 trace must still parse");
assert_eq!(
f.version, 1,
"the stored version must be preserved, not rewritten"
);
assert_eq!(
f.difficulty_hint,
DifficultyHint::None as u8,
"a missing hint must read as no-signal"
);
}
#[test]
fn token_bucket_is_monotonic_and_coarse() {
assert_eq!(token_bucket(0), 0);
assert_eq!(token_bucket(1), 0);
assert_eq!(token_bucket(2), 1);
assert_eq!(token_bucket(3), 1);
assert_eq!(token_bucket(4), 2);
assert_eq!(token_bucket(1024), 10);
let mut last = 0;
for n in 0..5000u64 {
let b = token_bucket(n);
assert!(b >= last);
last = b;
}
}
#[test]
fn repo_fingerprint_is_deterministic_salted_and_truncated() {
let a = repo_fingerprint("salt1", "github.com/acme/api");
assert_eq!(a, repo_fingerprint("salt1", "github.com/acme/api")); assert_ne!(a, repo_fingerprint("salt2", "github.com/acme/api")); assert_ne!(a, repo_fingerprint("salt1", "github.com/acme/web")); assert_eq!(a.len(), 16);
assert!(a.chars().all(|c| c.is_ascii_hexdigit()));
assert_ne!(repo_fingerprint("a", "bc"), repo_fingerprint("ab", "c"));
}
#[test]
fn hour_bucket_in_range() {
let ts: jiff::Timestamp = "2026-07-08T15:04:05Z".parse().unwrap();
assert_eq!(hour_bucket(ts), 15);
let midnight: jiff::Timestamp = "2026-01-01T00:00:00Z".parse().unwrap();
assert_eq!(hour_bucket(midnight), 0);
}
#[test]
fn features_default_version_stamped() {
let f = Features::new(TaskKind::CodeEdit);
assert_eq!(f.version, FEATURE_VERSION);
assert_eq!(f.task_kind, TaskKind::CodeEdit);
}
}
#[cfg(test)]
mod v1_chain_regression {
use super::*;
#[test]
fn a_v1_feature_vector_round_trips_to_its_original_canonical_json() {
let v1 = r#"{"version":1,"task_kind":"other","prompt_token_bucket":3,"tool_count":0,"has_images":false,"session_failure_count":0,"hour_bucket":9}"#;
let f: Features = serde_json::from_str(v1).expect("v1 must parse");
let reserialized = serde_json::to_string(&f).expect("must serialize");
assert!(
!reserialized.contains("difficulty_hint"),
"re-serializing a v1 vector must NOT emit the v2 field, or every historical receipt \
re-derives to a different hash and reads as TAMPERED: {reserialized}"
);
}
#[test]
fn a_v1_receipt_hash_is_still_re_derivable_by_todays_binary() {
let v1 = r#"{"version":1,"task_kind":"other","prompt_token_bucket":3,"tool_count":0,"has_images":false,"session_failure_count":0,"hour_bucket":9}"#;
let original: serde_json::Value = serde_json::from_str(v1).expect("v1 must parse");
let hash_then = crate::hashchain::record_hash(&original).expect("must hash");
let f: Features = serde_json::from_str(v1).expect("v1 must parse into v2 struct");
let hash_now = crate::hashchain::record_hash(&f).expect("must hash");
assert_eq!(
hash_then, hash_now,
"a v1 record must re-derive to its original hash; a mismatch is reported to the \
operator as TAMPERED, with no tampering having occurred"
);
}
#[test]
fn a_v2_vector_with_a_real_hint_still_serializes_it() {
let mut f = Features::new(TaskKind::CodeEdit);
f.difficulty_hint = DifficultyHint::High.as_u8();
let s = serde_json::to_string(&f).expect("must serialize");
assert!(
s.contains("\"difficulty_hint\":3"),
"a non-default hint must appear in the receipt: {s}"
);
}
}