pub struct Features {
pub version: u32,
pub task_kind: TaskKind,
pub language: Option<String>,
pub agent: Option<String>,
pub subagent: Option<String>,
pub prompt_token_bucket: u32,
pub tool_count: u32,
pub has_images: bool,
pub repo_fingerprint: Option<String>,
pub session_failure_count: u32,
pub difficulty_hint: u8,
pub hour_bucket: u8,
}Expand description
The per-request feature vector (§9.2).
Rolling per-bucket statistics (e.g. prior_rung_clearance) are intentionally not
here — they live in the trace store, not the deterministic per-request contract.
Fields§
§version: u32Feature-extraction contract version (features@vN).
task_kind: TaskKindCoarse task classification.
language: Option<String>Programming language, when known (lowercased identifier, e.g. "rust").
agent: Option<String>Calling agent identity, when known (e.g. "compass").
subagent: Option<String>Calling subagent identity, when known (e.g. "test-runner").
prompt_token_bucket: u32Coarse bucket of the prompt’s token count (see token_bucket) — never the raw count.
tool_count: u32Number of tools/functions offered in the request.
has_images: boolWhether the request carried image content.
repo_fingerprint: Option<String>Salted, truncated hash of the repository identity (see repo_fingerprint) — never a path.
session_failure_count: u32How many attempts have already failed in this session (drives session promotion, §8.4).
difficulty_hint: u8How hard the agent’s own conversation looks, 0..=3 — see DifficultyHint.
Distinct from Features::session_failure_count, and the distinction is the whole point.
That field counts our gate’s failures: endogenous evidence, available only after we have
already paid for a failed attempt. This one reads the agent’s failures out of the
transcript it sent us — failing tool calls, repeated identical actions, a long unproductive
exchange — which is evidence we get before spending anything, and which is present on turns
where our own gate would have passed.
0 means “no signal”, which is what a single-shot request, a non-agent client, and an
unparseable body all produce. It is a routing hint and never a serving decision: it may
choose which rung to start on, never what is fit to serve. Only a gate decides that.
skip_serializing_if is load-bearing for the hash chain, not a size optimisation. A v1
trace’s JSON has no such field; serde defaults it to 0 on read, and if re-serialization
emitted "difficulty_hint":0 the canonical JSON would differ from the bytes that were
originally hashed. Every historical receipt would then re-derive to a different hash and
firstpass verify would report TAMPERED across the whole store — breaking invariant #1
(“the hash chain is re-derivable”) on upgrade, with no tampering having occurred.
Omitting the default is exactly right rather than merely convenient: a v1 trace had no hint, and a receipt should say what was measured, not what a later version would have defaulted to. A v2 request carrying a real hint serialises it normally.
hour_bucket: u8Hour-of-day bucket in UTC, 0..=23 (see hour_bucket).