use serde::{Deserialize, Serialize};
use crate::{
ActivationTelemetryDispositionV1, CoreError, Digest, MAX_SPECULATIVE_TOKENS,
TextModelTopologyV1, TextSpeculativeMechanismV1, TokenId,
};
pub const MAX_SPECULATION_SEQUENCES: u32 = 4_096;
pub const MAX_SPECULATION_BOUNDARIES: usize = 1_048_576;
pub const MAX_SPECULATION_TELEMETRY_RESOLUTIONS: usize = 65_536;
pub const MAX_SPECULATION_STATE_BYTES: u64 = 64 * 1024 * 1024;
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
pub enum SpeculationActivationPolicyV1 {
None,
TargetOnly {
target_program: Digest,
},
SeparateDraftProgram {
target_program: Digest,
draft_program: Digest,
},
}
impl SpeculationActivationPolicyV1 {
pub const fn target_program(&self) -> Option<&Digest> {
match self {
Self::None => None,
Self::TargetOnly { target_program }
| Self::SeparateDraftProgram { target_program, .. } => Some(target_program),
}
}
pub const fn draft_program(&self) -> Option<&Digest> {
match self {
Self::SeparateDraftProgram { draft_program, .. } => Some(draft_program),
Self::None | Self::TargetOnly { .. } => None,
}
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SpeculationPlanV1 {
pub target_model: Digest,
pub target_topology: Digest,
pub draft_model: Digest,
pub draft_topology: Digest,
pub implementation: Digest,
pub mechanism: TextSpeculativeMechanismV1,
pub sequences: u32,
pub maximum_draft_tokens: u32,
pub minimum_draft_tokens: u32,
pub probability_floor_bits: u32,
pub activation: SpeculationActivationPolicyV1,
}
impl SpeculationPlanV1 {
pub fn probability_floor(&self) -> Result<f32, CoreError> {
let value = f32::from_bits(self.probability_floor_bits);
if !value.is_finite() || !(0.0..=1.0).contains(&value) {
return Err(CoreError::invalid(
"speculation probability floor",
"value must be finite and between zero and one",
));
}
Ok(value)
}
pub fn digest_for(
&self,
target: &TextModelTopologyV1,
draft: &TextModelTopologyV1,
) -> Result<Digest, CoreError> {
let target_topology = target.digest()?;
let draft_topology = draft.digest()?;
if self.target_model != target.model
|| self.target_topology != target_topology
|| self.draft_model != draft.model
|| self.draft_topology != draft_topology
{
return Err(CoreError::invalid(
"speculation plan",
"model or topology lineage does not match",
));
}
if !target.supported_speculation.contains(&self.mechanism) {
return Err(CoreError::invalid(
"speculation plan",
"target topology does not report the selected mechanism",
));
}
match self.mechanism {
TextSpeculativeMechanismV1::Mtp => {
if target.model != draft.model || target_topology != draft_topology {
return Err(CoreError::invalid(
"speculation plan",
"MTP requires target and draft contexts over one exact topology",
));
}
if target.nextn_layers == 0 {
return Err(CoreError::invalid(
"speculation plan",
"MTP requires at least one reported NextN layer",
));
}
}
TextSpeculativeMechanismV1::Eagle3 => {
if target.model == draft.model {
return Err(CoreError::invalid(
"speculation plan",
"EAGLE-3 requires a separately identified draft model",
));
}
}
}
if self.sequences == 0 || self.sequences > MAX_SPECULATION_SEQUENCES {
return Err(CoreError::invalid(
"speculation plan",
"sequence count is outside the supported bound",
));
}
if self.maximum_draft_tokens == 0
|| self.maximum_draft_tokens > MAX_SPECULATIVE_TOKENS
|| self.minimum_draft_tokens > self.maximum_draft_tokens
{
return Err(CoreError::invalid(
"speculation plan",
"draft token bounds are inconsistent or excessive",
));
}
self.probability_floor()?;
Digest::of_serializable("speculation-plan-v1", self)
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SpeculationTelemetryResolutionV1 {
pub provisional: Digest,
pub disposition: ActivationTelemetryDispositionV1,
pub resolved: Digest,
}
impl SpeculationTelemetryResolutionV1 {
fn validate(&self) -> Result<(), CoreError> {
if self.disposition == ActivationTelemetryDispositionV1::Provisional {
return Err(CoreError::invalid(
"speculation telemetry resolution",
"final disposition cannot remain provisional",
));
}
Ok(())
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SpeculationBoundaryReceiptV1 {
pub plan: Digest,
pub boundary: u64,
pub proposal: Digest,
pub proposed: u32,
pub accepted: u32,
pub rejected: u32,
#[serde(default)]
pub telemetry: Vec<SpeculationTelemetryResolutionV1>,
}
impl SpeculationBoundaryReceiptV1 {
pub fn from_tokens(
plan: &SpeculationPlanV1,
plan_identity: Digest,
boundary: u64,
proposed_tokens: &[TokenId],
accepted: u32,
telemetry: Vec<SpeculationTelemetryResolutionV1>,
) -> Result<Self, CoreError> {
let proposed = u32::try_from(proposed_tokens.len()).map_err(|_| {
CoreError::invalid("speculation boundary", "proposal length exceeds u32")
})?;
if proposed > plan.maximum_draft_tokens || accepted > proposed {
return Err(CoreError::invalid(
"speculation boundary",
"proposal or accepted-prefix count is invalid",
));
}
let rejected = proposed
.checked_sub(accepted)
.ok_or_else(|| CoreError::invalid("speculation boundary", "count underflowed"))?;
let receipt = Self {
plan: plan_identity,
boundary,
proposal: Digest::of_serializable(
"speculation-proposal-token-ids-v1",
proposed_tokens,
)?,
proposed,
accepted,
rejected,
telemetry,
};
receipt.validate_for(plan)?;
Ok(receipt)
}
pub fn validate_for(&self, plan: &SpeculationPlanV1) -> Result<(), CoreError> {
if self.plan != Digest::of_serializable("speculation-plan-v1", plan)?
|| self.proposed > plan.maximum_draft_tokens
|| self.accepted > self.proposed
|| self.rejected != self.proposed - self.accepted
|| self.telemetry.len() > MAX_SPECULATION_TELEMETRY_RESOLUTIONS
{
return Err(CoreError::invalid(
"speculation boundary receipt",
"plan lineage, counts, or telemetry bounds are invalid",
));
}
for resolution in &self.telemetry {
resolution.validate()?;
}
Ok(())
}
pub fn digest_for(&self, plan: &SpeculationPlanV1) -> Result<Digest, CoreError> {
self.validate_for(plan)?;
Digest::of_serializable("speculation-boundary-receipt-v1", self)
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SpeculationReceiptV1 {
pub plan: Digest,
pub boundaries: Vec<Digest>,
pub proposed: u64,
pub accepted: u64,
pub rejected: u64,
}
impl SpeculationReceiptV1 {
pub fn from_boundaries(
plan: &SpeculationPlanV1,
boundaries: &[SpeculationBoundaryReceiptV1],
) -> Result<Self, CoreError> {
if boundaries.len() > MAX_SPECULATION_BOUNDARIES {
return Err(CoreError::invalid(
"speculation receipt",
"boundary count exceeds the supported bound",
));
}
let plan_identity = Digest::of_serializable("speculation-plan-v1", plan)?;
let mut identities = Vec::with_capacity(boundaries.len());
let mut proposed = 0_u64;
let mut accepted = 0_u64;
let mut rejected = 0_u64;
for (index, boundary) in boundaries.iter().enumerate() {
let expected = u64::try_from(index).map_err(|_| {
CoreError::invalid("speculation receipt", "boundary index exceeds u64")
})?;
if boundary.boundary != expected || boundary.plan != plan_identity {
return Err(CoreError::invalid(
"speculation receipt",
"boundaries must be contiguous and plan-bound",
));
}
identities.push(boundary.digest_for(plan)?);
proposed = proposed
.checked_add(u64::from(boundary.proposed))
.ok_or_else(|| {
CoreError::invalid("speculation receipt", "proposal count overflowed")
})?;
accepted = accepted
.checked_add(u64::from(boundary.accepted))
.ok_or_else(|| {
CoreError::invalid("speculation receipt", "acceptance count overflowed")
})?;
rejected = rejected
.checked_add(u64::from(boundary.rejected))
.ok_or_else(|| {
CoreError::invalid("speculation receipt", "rejection count overflowed")
})?;
}
Ok(Self {
plan: plan_identity,
boundaries: identities,
proposed,
accepted,
rejected,
})
}
pub fn digest_for(
&self,
plan: &SpeculationPlanV1,
boundaries: &[SpeculationBoundaryReceiptV1],
) -> Result<Digest, CoreError> {
if *self != Self::from_boundaries(plan, boundaries)? {
return Err(CoreError::invalid(
"speculation receipt",
"aggregate evidence does not match its boundary receipts",
));
}
Digest::of_serializable("speculation-receipt-v1", self)
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SpeculativeCheckpointReceiptV1 {
pub mechanics: Digest,
pub speculation: Digest,
pub target_state: Digest,
pub draft_state: Digest,
pub implementation_state: Digest,
pub implementation_state_bytes: u64,
pub target_sampler_lineage: Digest,
pub admitted_history: Digest,
pub position: u64,
pub completed_boundaries: u64,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub target_activation: Option<Digest>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub draft_activation: Option<Digest>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub parent: Option<Digest>,
}
impl SpeculativeCheckpointReceiptV1 {
pub fn digest_for(&self, plan: &SpeculationPlanV1) -> Result<Digest, CoreError> {
if self.speculation != Digest::of_serializable("speculation-plan-v1", plan)?
|| self.implementation_state_bytes == 0
|| self.implementation_state_bytes > MAX_SPECULATION_STATE_BYTES
|| self.target_activation != plan.activation.target_program().cloned()
|| self.draft_activation != plan.activation.draft_program().cloned()
{
return Err(CoreError::invalid(
"speculative checkpoint receipt",
"state bounds or plan lineage are invalid",
));
}
Digest::of_serializable("speculative-checkpoint-receipt-v1", self)
}
}
#[cfg(test)]
mod tests {
use super::*;
fn topology(model: &[u8], mtp: bool) -> TextModelTopologyV1 {
TextModelTopologyV1 {
model: Digest::of_bytes("test-model", model),
backend: Digest::of_bytes("test-backend", b"one"),
architecture_implementation: Digest::of_bytes("test-architecture", b"one"),
layers: 4,
embedding_width: 8,
experts: None,
experts_used: None,
nextn_layers: u32::from(mtp),
supported_speculation: if mtp {
vec![
TextSpeculativeMechanismV1::Mtp,
TextSpeculativeMechanismV1::Eagle3,
]
} else {
vec![TextSpeculativeMechanismV1::Eagle3]
},
}
}
fn mtp_plan(topology: &TextModelTopologyV1) -> SpeculationPlanV1 {
SpeculationPlanV1 {
target_model: topology.model.clone(),
target_topology: topology.digest().unwrap(),
draft_model: topology.model.clone(),
draft_topology: topology.digest().unwrap(),
implementation: Digest::of_bytes("test-speculation", b"one"),
mechanism: TextSpeculativeMechanismV1::Mtp,
sequences: 1,
maximum_draft_tokens: 4,
minimum_draft_tokens: 0,
probability_floor_bits: 0.0_f32.to_bits(),
activation: SpeculationActivationPolicyV1::None,
}
}
#[test]
fn mtp_requires_one_exact_model_topology() {
let target = topology(b"target", true);
let mut plan = mtp_plan(&target);
assert!(plan.digest_for(&target, &target).is_ok());
let draft = topology(b"draft", true);
plan.draft_model = draft.model.clone();
plan.draft_topology = draft.digest().unwrap();
assert!(plan.digest_for(&target, &draft).is_err());
}
#[test]
fn eagle_requires_a_separate_draft_identity() {
let target = topology(b"target", true);
let draft = topology(b"draft", false);
let plan = SpeculationPlanV1 {
target_model: target.model.clone(),
target_topology: target.digest().unwrap(),
draft_model: draft.model.clone(),
draft_topology: draft.digest().unwrap(),
implementation: Digest::of_bytes("test-speculation", b"one"),
mechanism: TextSpeculativeMechanismV1::Eagle3,
sequences: 1,
maximum_draft_tokens: 4,
minimum_draft_tokens: 0,
probability_floor_bits: 0.1_f32.to_bits(),
activation: SpeculationActivationPolicyV1::None,
};
assert!(plan.digest_for(&target, &draft).is_ok());
}
#[test]
fn boundaries_preserve_zero_partial_and_complete_acceptance() {
let topology = topology(b"target", true);
let plan = mtp_plan(&topology);
let plan_identity = plan.digest_for(&topology, &topology).unwrap();
let proposed = [
TokenId::new(1).unwrap(),
TokenId::new(2).unwrap(),
TokenId::new(3).unwrap(),
];
let boundaries = [0_u32, 2, 3]
.into_iter()
.enumerate()
.map(|(index, accepted)| {
SpeculationBoundaryReceiptV1::from_tokens(
&plan,
plan_identity.clone(),
u64::try_from(index).unwrap(),
&proposed,
accepted,
Vec::new(),
)
.unwrap()
})
.collect::<Vec<_>>();
let receipt = SpeculationReceiptV1::from_boundaries(&plan, &boundaries).unwrap();
assert_eq!(receipt.proposed, 9);
assert_eq!(receipt.accepted, 5);
assert_eq!(receipt.rejected, 4);
assert!(receipt.digest_for(&plan, &boundaries).is_ok());
}
#[test]
fn pre_boundary_terminal_selection_has_zeroed_speculation_accounting() {
let topology = topology(b"target", true);
let plan = mtp_plan(&topology);
let receipt = SpeculationReceiptV1::from_boundaries(&plan, &[]).unwrap();
assert!(receipt.boundaries.is_empty());
assert_eq!(
(receipt.proposed, receipt.accepted, receipt.rejected),
(0, 0, 0)
);
assert!(receipt.digest_for(&plan, &[]).is_ok());
}
#[test]
fn provisional_telemetry_requires_a_final_disposition() {
let resolution = SpeculationTelemetryResolutionV1 {
provisional: Digest::of_bytes("test-provisional", b"one"),
disposition: ActivationTelemetryDispositionV1::Provisional,
resolved: Digest::of_bytes("test-resolved", b"one"),
};
assert!(resolution.validate().is_err());
}
}