use std::collections::HashSet;
use std::sync::Arc;
use async_trait::async_trait;
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use sha2::{Digest, Sha256};
use thiserror::Error;
use crate::effects::{derive_effect_id, ApprovalToken, EffectId};
use crate::error::{Result, RustyError};
use crate::journal::JournalSnapshot;
use crate::memory::{
apply_query, MemoryQuery, MemoryRecord, MemoryScope, MemoryStore, ProvenanceAuthor,
ScopeAddress,
};
use crate::record::{sha256_hex, DecisionFamily, RunManifest};
fn invalid(message: impl Into<String>) -> RustyError {
RustyError::InvalidUpdate(message.into())
}
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(transparent)]
pub struct CandidateId(String);
impl CandidateId {
pub fn as_str(&self) -> &str {
&self.0
}
}
impl std::fmt::Display for CandidateId {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(&self.0)
}
}
impl From<String> for CandidateId {
fn from(digest: String) -> Self {
Self(digest)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CandidateKind {
Prompt,
Policy,
MemorySet,
ToolPermission,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum GrantDirection {
Narrow,
Widen,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum CandidateContent {
Prompt {
name: String,
prompt: String,
},
Policy {
family: DecisionFamily,
parameters: Value,
},
MemorySet {
scope: ScopeAddress,
adds: Vec<MemoryRecord>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
supersedes: Vec<String>,
},
ToolPermission {
tool: String,
direction: GrantDirection,
},
}
pub fn derive_candidate_id(content: &CandidateContent) -> Result<CandidateId> {
Ok(CandidateId(sha256_hex(&serde_json::to_vec(content)?)))
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct EvidenceSpan {
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub run_ids: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub correction_ids: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub memory_ids: Vec<String>,
}
impl EvidenceSpan {
pub fn is_empty(&self) -> bool {
self.run_ids.is_empty() && self.correction_ids.is_empty() && self.memory_ids.is_empty()
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Candidate {
pub candidate_id: CandidateId,
pub content: CandidateContent,
pub distilled_by: ProvenanceAuthor,
#[serde(default, skip_serializing_if = "EvidenceSpan::is_empty")]
pub evidence: EvidenceSpan,
pub created_at: DateTime<Utc>,
}
impl Candidate {
pub fn new(
content: CandidateContent,
distilled_by: ProvenanceAuthor,
evidence: EvidenceSpan,
created_at: DateTime<Utc>,
) -> Result<Self> {
let candidate_id = derive_candidate_id(&content)?;
Ok(Self {
candidate_id,
content,
distilled_by,
evidence,
created_at,
})
}
pub fn kind(&self) -> CandidateKind {
match &self.content {
CandidateContent::Prompt { .. } => CandidateKind::Prompt,
CandidateContent::Policy { .. } => CandidateKind::Policy,
CandidateContent::MemorySet { .. } => CandidateKind::MemorySet,
CandidateContent::ToolPermission { .. } => CandidateKind::ToolPermission,
}
}
pub fn surface(&self) -> SurfaceKey {
match &self.content {
CandidateContent::Prompt { name, .. } => SurfaceKey::new(format!("prompt:{name}")),
CandidateContent::Policy { family, .. } => {
let family = serde_json::to_value(family)
.ok()
.and_then(|v| v.as_str().map(str::to_owned))
.unwrap_or_else(|| format!("{family:?}").to_lowercase());
SurfaceKey::new(format!("policy:{family}"))
}
CandidateContent::MemorySet { scope, .. } => {
SurfaceKey::new(format!("memory:{}", scope.as_address()))
}
CandidateContent::ToolPermission { tool, .. } => {
SurfaceKey::new(format!("tool:{tool}"))
}
}
}
pub fn verify_address(&self) -> std::result::Result<(), LearnError> {
let derived = derive_candidate_id(&self.content)
.map_err(|e| LearnError::UnaddressableContent(e.to_string()))?;
if derived != self.candidate_id {
return Err(LearnError::AddressMismatch {
claimed: self.candidate_id.clone(),
derived,
});
}
Ok(())
}
pub fn apply_to_manifest(&self, manifest: &mut RunManifest) -> Result<()> {
let CandidateContent::Prompt { name, prompt } = &self.content else {
return Err(invalid(format!(
"only a `prompt` candidate applies to a run manifest; `{}` candidates apply \
to their own surfaces",
self.kind_str()
)));
};
manifest
.prompts
.insert(name.clone(), sha256_hex(prompt.as_bytes()));
Ok(())
}
fn kind_str(&self) -> &'static str {
match self.kind() {
CandidateKind::Prompt => "prompt",
CandidateKind::Policy => "policy",
CandidateKind::MemorySet => "memory_set",
CandidateKind::ToolPermission => "tool_permission",
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(transparent)]
pub struct SurfaceKey(String);
impl SurfaceKey {
pub fn new(surface: impl Into<String>) -> Self {
Self(surface.into())
}
pub fn as_str(&self) -> &str {
&self.0
}
}
impl std::fmt::Display for SurfaceKey {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(&self.0)
}
}
pub fn candidate_effect_key(candidate_id: &CandidateId) -> String {
format!("candidate:{candidate_id}")
}
pub fn evaluation_effect_key(candidate_id: &CandidateId, dataset_version: &str) -> String {
format!("evaluation:{candidate_id}:{dataset_version}")
}
pub fn promotion_effect_key(candidate_id: &CandidateId) -> String {
format!("promotion:{candidate_id}")
}
pub fn rollback_effect_key(surface: &SurfaceKey, candidate_id: &CandidateId) -> String {
format!("rollback:{surface}:{candidate_id}")
}
pub const PROMOTION_EFFECT_KIND: &str = "candidate_promotion";
pub fn promotion_effect_id(candidate: &Candidate) -> EffectId {
derive_effect_id(
candidate.surface().as_str(),
PROMOTION_EFFECT_KIND,
candidate.candidate_id.as_str(),
Some(&promotion_effect_key(&candidate.candidate_id)),
)
}
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct EvaluationThresholds {
pub max_pass_rate_drop: f64,
pub max_latency_p95_ratio: f64,
}
impl Default for EvaluationThresholds {
fn default() -> Self {
Self {
max_pass_rate_drop: 0.05,
max_latency_p95_ratio: 1.25,
}
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct EvaluationVerdict {
pub regressed: bool,
pub target_metric: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub baseline: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub candidate: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub delta: Option<f64>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ReplayDivergence {
pub fixture_id: String,
pub detail: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ReplaySummary {
pub fixture_ids: Vec<String>,
pub matched: usize,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub divergences: Vec<ReplayDivergence>,
}
impl ReplaySummary {
pub fn is_clean(&self) -> bool {
self.divergences.is_empty() && self.matched == self.fixture_ids.len()
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CandidateEvaluation {
pub candidate_id: CandidateId,
pub dataset_version: String,
pub replay: ReplaySummary,
pub baseline_report: Value,
pub candidate_report: Value,
pub verdict: EvaluationVerdict,
pub thresholds: EvaluationThresholds,
pub evaluated_by: ProvenanceAuthor,
pub evaluated_at: DateTime<Utc>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EvaluationRequest {
pub dataset_version: String,
pub target_metric: String,
pub thresholds: EvaluationThresholds,
pub replay_evidence: Vec<JournalSnapshot>,
}
#[async_trait]
pub trait CandidateEvaluator: Send + Sync + std::fmt::Debug {
async fn evaluate(
&self,
candidate: &Candidate,
request: &EvaluationRequest,
) -> Result<CandidateEvaluation>;
}
#[derive(Debug)]
pub struct CandidateOverlay {
base: Arc<dyn MemoryStore>,
adds: Vec<MemoryRecord>,
supersedes: HashSet<String>,
}
impl CandidateOverlay {
pub fn new(base: Arc<dyn MemoryStore>, candidate: &Candidate) -> Result<Self> {
let CandidateContent::MemorySet {
adds, supersedes, ..
} = &candidate.content
else {
return Err(invalid(format!(
"only a `memory_set` candidate applies as a memory overlay; `{}` candidates \
apply to their own surfaces",
match candidate.kind() {
CandidateKind::Prompt => "prompt",
CandidateKind::Policy => "policy",
CandidateKind::MemorySet => unreachable!(),
CandidateKind::ToolPermission => "tool_permission",
}
)));
};
Ok(Self {
base,
adds: adds.clone(),
supersedes: supersedes.iter().cloned().collect(),
})
}
}
#[async_trait]
impl MemoryStore for CandidateOverlay {
async fn put(&self, _record: &MemoryRecord) -> Result<bool> {
Err(invalid(
"the candidate overlay is a read lens: writes through it would mutate production \
memory mid-evaluation — the silent-rewrite pattern the candidate pipeline exists \
to forbid",
))
}
async fn get(&self, memory_id: &str) -> Result<Option<MemoryRecord>> {
if let Some(record) = self.adds.iter().find(|r| r.memory_id == memory_id) {
return Ok(Some(record.clone()));
}
self.base.get(memory_id).await
}
async fn all(&self) -> Result<Vec<MemoryRecord>> {
let mut merged: Vec<MemoryRecord> = self
.base
.all()
.await?
.into_iter()
.filter(|record| {
!self
.adds
.iter()
.any(|add| add.memory_id == record.memory_id)
})
.collect();
merged.extend(self.adds.iter().cloned());
Ok(merged)
}
async fn remove(&self, _memory_id: &str) -> Result<bool> {
Err(invalid(
"the candidate overlay is a read lens: deletion through it would mutate production \
memory mid-evaluation",
))
}
async fn query(&self, query: &MemoryQuery, now: DateTime<Utc>) -> Result<Vec<MemoryRecord>> {
let matched = apply_query(&self.all().await?, query, now);
if query.include_superseded || self.supersedes.is_empty() {
return Ok(matched);
}
Ok(matched
.into_iter()
.filter(|record| !self.supersedes.contains(&record.memory_id))
.collect())
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct AutoPromotion {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub dataset_version: Option<String>,
pub min_improvement: f64,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub scopes: Vec<MemoryScope>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "mode", rename_all = "snake_case")]
pub enum EnvelopeRule {
Auto(AutoPromotion),
Approval,
Canary {
fraction: f64,
auto: AutoPromotion,
},
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PromotionEnvelope {
pub envelope_version: String,
pub prompt: EnvelopeRule,
pub policy: EnvelopeRule,
pub memory_set: EnvelopeRule,
pub tool_permission: EnvelopeRule,
}
impl PromotionEnvelope {
pub fn r08_default() -> Self {
Self {
envelope_version: "r0.8-default".to_owned(),
prompt: EnvelopeRule::Approval,
policy: EnvelopeRule::Approval,
memory_set: EnvelopeRule::Auto(AutoPromotion {
dataset_version: None,
min_improvement: 0.0,
scopes: vec![MemoryScope::Run, MemoryScope::Agent],
}),
tool_permission: EnvelopeRule::Approval,
}
}
pub fn rule_for(&self, kind: CandidateKind) -> &EnvelopeRule {
match kind {
CandidateKind::Prompt => &self.prompt,
CandidateKind::Policy => &self.policy,
CandidateKind::MemorySet => &self.memory_set,
CandidateKind::ToolPermission => &self.tool_permission,
}
}
pub fn validate(&self) -> Result<()> {
for rule in [
&self.prompt,
&self.policy,
&self.memory_set,
&self.tool_permission,
] {
match rule {
EnvelopeRule::Auto(auto) => check_auto(auto)?,
EnvelopeRule::Canary { fraction, auto } => {
if !(fraction.is_finite() && *fraction > 0.0 && *fraction <= 1.0) {
return Err(invalid(format!(
"canary fraction must be in (0, 1], got {fraction} — a fraction \
outside the interval binds nothing or everything, and both are \
silent full promotions or silent no-ops"
)));
}
check_auto(auto)?;
}
EnvelopeRule::Approval => {}
}
}
Ok(())
}
}
fn check_auto(auto: &AutoPromotion) -> Result<()> {
if !(auto.min_improvement.is_finite() && auto.min_improvement >= 0.0) {
return Err(invalid(format!(
"min_improvement must be finite and non-negative, got {} — a negative bar would \
auto-promote regressions, which is the one outcome the gate exists to refuse",
auto.min_improvement
)));
}
Ok(())
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CanaryBinding {
pub candidate_id: CandidateId,
pub fraction: f64,
}
pub const CANARY_DRAW_DOMAIN: &str = "rusty/canary-draw/v1";
pub fn canary_admits(binding: &CanaryBinding, surface: &SurfaceKey, run_id: &str) -> bool {
if binding.fraction >= 1.0 {
return true;
}
let material = [
CANARY_DRAW_DOMAIN,
surface.as_str(),
binding.candidate_id.as_str(),
run_id,
]
.join("\n");
let mut hasher = Sha256::new();
hasher.update(material.as_bytes());
let digest = hasher.finalize();
let draw = u64::from_be_bytes(digest[..8].try_into().expect("eight bytes"));
(draw as f64) < binding.fraction * (u64::MAX as f64)
}
#[derive(Debug, Clone, PartialEq, Error)]
pub enum PromotionRefusal {
#[error(
"candidate `{candidate_id}` has no journaled evaluation: promotion is gated on \
evidence — a human approves reviewed evidence, never a blank check"
)]
NotEvaluated {
candidate_id: CandidateId,
},
#[error(
"evaluation names candidate `{evaluation}` but promotion was requested for \
`{candidate_id}` — the evidence must be the candidate's own"
)]
EvaluationMismatch {
candidate_id: CandidateId,
evaluation: CandidateId,
},
#[error(
"candidate `{candidate_id}` diverged under replay ({divergences} fixture(s)): a \
candidate that cannot reproduce its evidence never auto-promotes"
)]
ReplayDiverged {
candidate_id: CandidateId,
divergences: usize,
},
#[error(
"candidate `{candidate_id}` regressed against its baseline: the auto-promotion bar \
is no regression AND improvement — the evidence failed the first half"
)]
EvaluationRegressed {
candidate_id: CandidateId,
},
#[error(
"envelope requires a clean verdict over dataset `{required}` but the evaluation \
ran `{evaluated}` — the promotion bar names its evidence exactly"
)]
DatasetVersionMismatch {
required: String,
evaluated: String,
},
#[error(
"memory_set candidates at `{scope:?}` scope do not auto-promote under this envelope — \
the R0.8 default covers run and agent scope; wider scopes require an approval"
)]
ScopeNotAutoPromotable {
scope: MemoryScope,
},
#[error(
"target metric moved by {delta:?} but the envelope requires improvement past \
{required} — parity is not improvement, and the auto bar does not clear on it"
)]
InsufficientImprovement {
delta: Option<f64>,
required: f64,
},
#[error(
"this promotion is outside the envelope: present an approval token scoped to \
effect id {effect_id} — the scope check makes an approval for one candidate \
non-transferable to another"
)]
RequiresApproval {
effect_id: EffectId,
},
#[error(
"approval token for {presented} does not admit this promotion ({required}) — an \
approval is scoped to exactly one candidate's promotion and is not transferable"
)]
ApprovalMismatch {
required: EffectId,
presented: EffectId,
},
}
#[derive(Debug, Clone, PartialEq, Error)]
pub enum LearnError {
#[error(
"candidate address mismatch: id {claimed} does not re-derive from the content \
(derived {derived}) — identity is integrity, and a tampered candidate fails its \
own address"
)]
AddressMismatch {
claimed: CandidateId,
derived: CandidateId,
},
#[error("candidate content could not be addressed: {0}")]
UnaddressableContent(String),
#[error(
"invalid candidate transition: cannot {action} from status `{from:?}` — refused \
transitions are errors, not silent no-ops"
)]
InvalidTransition {
from: CandidateStatus,
action: &'static str,
},
#[error(
"receipt names candidate `{named}` but the record is `{candidate_id}` — a receipt \
applies to the candidate it was minted for, never to another"
)]
ReceiptMismatch {
candidate_id: CandidateId,
named: CandidateId,
},
#[error("{0}")]
Refused(#[from] PromotionRefusal),
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PromotionDecision {
pub authority: PromotionAuthority,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub canary: Option<CanaryBinding>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "authority", rename_all = "snake_case")]
pub enum PromotionAuthority {
Envelope {
envelope_version: String,
},
Approval {
approved_by: String,
},
}
pub fn admit_promotion(
envelope: &PromotionEnvelope,
candidate: &Candidate,
evaluation: Option<&CandidateEvaluation>,
approval: Option<&ApprovalToken>,
) -> std::result::Result<PromotionDecision, LearnError> {
candidate.verify_address()?;
let evaluation = evaluation.ok_or(PromotionRefusal::NotEvaluated {
candidate_id: candidate.candidate_id.clone(),
})?;
if evaluation.candidate_id != candidate.candidate_id {
return Err(PromotionRefusal::EvaluationMismatch {
candidate_id: candidate.candidate_id.clone(),
evaluation: evaluation.candidate_id.clone(),
}
.into());
}
match envelope.rule_for(candidate.kind()) {
EnvelopeRule::Auto(auto) => {
check_evidence_bar(auto, candidate, evaluation)?;
Ok(PromotionDecision {
authority: PromotionAuthority::Envelope {
envelope_version: envelope.envelope_version.clone(),
},
canary: None,
})
}
EnvelopeRule::Canary { fraction, auto } => {
check_evidence_bar(auto, candidate, evaluation)?;
Ok(PromotionDecision {
authority: PromotionAuthority::Envelope {
envelope_version: envelope.envelope_version.clone(),
},
canary: Some(CanaryBinding {
candidate_id: candidate.candidate_id.clone(),
fraction: *fraction,
}),
})
}
EnvelopeRule::Approval => {
let required = promotion_effect_id(candidate);
let token = approval.ok_or(PromotionRefusal::RequiresApproval {
effect_id: required.clone(),
})?;
if !token.admits(&required) {
return Err(PromotionRefusal::ApprovalMismatch {
required,
presented: token.effect_id().clone(),
}
.into());
}
Ok(PromotionDecision {
authority: PromotionAuthority::Approval {
approved_by: token.approved_by().to_owned(),
},
canary: None,
})
}
}
}
fn check_evidence_bar(
auto: &AutoPromotion,
candidate: &Candidate,
evaluation: &CandidateEvaluation,
) -> std::result::Result<(), LearnError> {
if !evaluation.replay.is_clean() {
return Err(PromotionRefusal::ReplayDiverged {
candidate_id: candidate.candidate_id.clone(),
divergences: evaluation.replay.divergences.len(),
}
.into());
}
if evaluation.verdict.regressed {
return Err(PromotionRefusal::EvaluationRegressed {
candidate_id: candidate.candidate_id.clone(),
}
.into());
}
if let Some(required) = &auto.dataset_version {
if required != &evaluation.dataset_version {
return Err(PromotionRefusal::DatasetVersionMismatch {
required: required.clone(),
evaluated: evaluation.dataset_version.clone(),
}
.into());
}
}
if let CandidateContent::MemorySet { scope, .. } = &candidate.content {
if !auto.scopes.is_empty() && !auto.scopes.contains(&scope.scope) {
return Err(PromotionRefusal::ScopeNotAutoPromotable { scope: scope.scope }.into());
}
}
let clears = evaluation
.verdict
.delta
.is_some_and(|delta| delta > auto.min_improvement);
if !clears {
return Err(PromotionRefusal::InsufficientImprovement {
delta: evaluation.verdict.delta,
required: auto.min_improvement,
}
.into());
}
Ok(())
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CandidateStatus {
Created,
Evaluated,
Promoted,
RolledBack,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PromotionReceipt {
pub candidate_id: CandidateId,
pub surface: SurfaceKey,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub previous: Option<CandidateId>,
pub decision: PromotionDecision,
pub promoted_at: DateTime<Utc>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RollbackReceipt {
pub surface: SurfaceKey,
pub from: CandidateId,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub to: Option<CandidateId>,
pub cause: String,
pub rolled_back_at: DateTime<Utc>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CandidateRecord {
pub candidate: Candidate,
pub status: CandidateStatus,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub evaluation: Option<CandidateEvaluation>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub promotion: Option<PromotionReceipt>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub rollback: Option<RollbackReceipt>,
}
impl CandidateRecord {
pub fn new(candidate: Candidate) -> Self {
Self {
candidate,
status: CandidateStatus::Created,
evaluation: None,
promotion: None,
rollback: None,
}
}
pub fn candidate_id(&self) -> &CandidateId {
&self.candidate.candidate_id
}
pub fn apply_evaluation(
&mut self,
evaluation: CandidateEvaluation,
) -> std::result::Result<(), LearnError> {
match self.status {
CandidateStatus::Created | CandidateStatus::Evaluated => {}
other => {
return Err(LearnError::InvalidTransition {
from: other,
action: "evaluate",
})
}
}
if evaluation.candidate_id != self.candidate.candidate_id {
return Err(PromotionRefusal::EvaluationMismatch {
candidate_id: self.candidate.candidate_id.clone(),
evaluation: evaluation.candidate_id,
}
.into());
}
self.evaluation = Some(evaluation);
self.status = CandidateStatus::Evaluated;
Ok(())
}
pub fn apply_promotion(
&mut self,
receipt: PromotionReceipt,
) -> std::result::Result<(), LearnError> {
if self.status != CandidateStatus::Evaluated {
return Err(LearnError::InvalidTransition {
from: self.status,
action: "promote",
});
}
if receipt.candidate_id != self.candidate.candidate_id {
return Err(LearnError::ReceiptMismatch {
candidate_id: self.candidate.candidate_id.clone(),
named: receipt.candidate_id,
});
}
self.promotion = Some(receipt);
self.status = CandidateStatus::Promoted;
Ok(())
}
pub fn apply_rollback(
&mut self,
receipt: RollbackReceipt,
) -> std::result::Result<(), LearnError> {
if self.status != CandidateStatus::Promoted {
return Err(LearnError::InvalidTransition {
from: self.status,
action: "roll back",
});
}
if receipt.from != self.candidate.candidate_id {
return Err(LearnError::ReceiptMismatch {
candidate_id: self.candidate.candidate_id.clone(),
named: receipt.from,
});
}
self.rollback = Some(receipt);
self.status = CandidateStatus::RolledBack;
Ok(())
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct VersionPointer {
pub surface: SurfaceKey,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub active: Option<CandidateId>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub canary: Option<CanaryBinding>,
}
impl VersionPointer {
pub fn new(surface: SurfaceKey) -> Self {
Self {
surface,
active: None,
canary: None,
}
}
pub fn promoted(&self, receipt: &PromotionReceipt) -> VersionPointer {
let mut next = self.clone();
if let Some(binding) = &receipt.decision.canary {
next.canary = Some(binding.clone());
} else {
next.active = Some(receipt.candidate_id.clone());
next.canary = None;
}
next
}
pub fn rolled_back(&self, receipt: &RollbackReceipt) -> VersionPointer {
let mut next = self.clone();
if self.active.as_ref() == Some(&receipt.from) {
next.active = receipt.to.clone();
}
if self
.canary
.as_ref()
.is_some_and(|binding| binding.candidate_id == receipt.from)
{
next.canary = None;
}
next
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::memory::{InMemoryMemoryStore, MemoryKind, MemoryProvenance, ValidityWindow};
use serde_json::json;
fn ts(millis: i64) -> DateTime<Utc> {
DateTime::<Utc>::from_timestamp_millis(millis).unwrap()
}
fn distiller() -> ProvenanceAuthor {
ProvenanceAuthor::Distiller {
name: "correction-loop".into(),
}
}
fn memory_record(content: Value) -> MemoryRecord {
MemoryRecord::new(
MemoryKind::Fact,
ScopeAddress::new(MemoryScope::Agent, "support-1"),
MemoryProvenance {
author: ProvenanceAuthor::Human {
human_id: "amjad".into(),
},
evidence: Default::default(),
written_at: ts(1_000),
},
1.0,
ValidityWindow::starting(ts(500)),
ts(1_000),
content,
)
.unwrap()
}
fn memory_set_candidate(content: Value) -> Candidate {
Candidate::new(
CandidateContent::MemorySet {
scope: ScopeAddress::new(MemoryScope::Agent, "support-1"),
adds: vec![memory_record(content)],
supersedes: Vec::new(),
},
distiller(),
EvidenceSpan {
run_ids: vec!["run-1".into()],
..EvidenceSpan::default()
},
ts(2_000),
)
.unwrap()
}
fn clean_evaluation(candidate: &Candidate, delta: f64) -> CandidateEvaluation {
CandidateEvaluation {
candidate_id: candidate.candidate_id.clone(),
dataset_version: "v3".into(),
replay: ReplaySummary {
fixture_ids: vec!["run-1".into()],
matched: 1,
divergences: Vec::new(),
},
baseline_report: json!({"name": "support@v3", "summary": {"run_pass_rate": 0.5}}),
candidate_report: json!({"name": "support@v3", "summary": {"run_pass_rate": 0.9}}),
verdict: EvaluationVerdict {
regressed: false,
target_metric: "run_pass_rate".into(),
baseline: Some(0.5),
candidate: Some(0.5 + delta),
delta: Some(delta),
},
thresholds: EvaluationThresholds::default(),
evaluated_by: distiller(),
evaluated_at: ts(3_000),
}
}
#[test]
fn candidate_id_is_a_content_address() {
let a = memory_set_candidate(json!({"tone": "warm"}));
let b = memory_set_candidate(json!({"tone": "warm"}));
let c = memory_set_candidate(json!({"tone": "cold"}));
assert_eq!(a.candidate_id, b.candidate_id);
let d = Candidate::new(
a.content.clone(),
ProvenanceAuthor::System,
EvidenceSpan::default(),
ts(9_999),
)
.unwrap();
assert_eq!(a.candidate_id, d.candidate_id);
assert_ne!(a.candidate_id, c.candidate_id);
assert_eq!(a.candidate_id.as_str().len(), 64);
}
#[test]
fn tampered_candidate_fails_its_own_address() {
let mut candidate = memory_set_candidate(json!({"tone": "warm"}));
candidate.verify_address().unwrap();
candidate.candidate_id = CandidateId("f".repeat(64));
assert!(matches!(
candidate.verify_address(),
Err(LearnError::AddressMismatch { .. })
));
}
#[test]
fn surfaces_are_the_documented_keys() {
let memory = memory_set_candidate(json!({}));
assert_eq!(memory.surface().as_str(), "memory:agent:support-1");
let prompt = Candidate::new(
CandidateContent::Prompt {
name: "system".into(),
prompt: "You are careful.".into(),
},
distiller(),
EvidenceSpan::default(),
ts(2_000),
)
.unwrap();
assert_eq!(prompt.surface().as_str(), "prompt:system");
let policy = Candidate::new(
CandidateContent::Policy {
family: DecisionFamily::Retry,
parameters: json!({"max_attempts": 4}),
},
distiller(),
EvidenceSpan::default(),
ts(2_000),
)
.unwrap();
assert_eq!(policy.surface().as_str(), "policy:retry");
let tool = Candidate::new(
CandidateContent::ToolPermission {
tool: "shell".into(),
direction: GrantDirection::Narrow,
},
distiller(),
EvidenceSpan::default(),
ts(2_000),
)
.unwrap();
assert_eq!(tool.surface().as_str(), "tool:shell");
}
#[test]
fn lifecycle_refuses_illegal_transitions() {
let candidate = memory_set_candidate(json!({}));
let mut record = CandidateRecord::new(candidate.clone());
let receipt = PromotionReceipt {
candidate_id: candidate.candidate_id.clone(),
surface: candidate.surface(),
previous: None,
decision: PromotionDecision {
authority: PromotionAuthority::Envelope {
envelope_version: "r0.8-default".into(),
},
canary: None,
},
promoted_at: ts(4_000),
};
assert!(matches!(
record.apply_promotion(receipt.clone()),
Err(LearnError::InvalidTransition {
from: CandidateStatus::Created,
action: "promote",
})
));
record
.apply_evaluation(clean_evaluation(&candidate, 0.4))
.unwrap();
record.apply_promotion(receipt).unwrap();
assert!(matches!(
record.apply_evaluation(clean_evaluation(&candidate, 0.5)),
Err(LearnError::InvalidTransition {
from: CandidateStatus::Promoted,
action: "evaluate",
})
));
record
.apply_rollback(RollbackReceipt {
surface: candidate.surface(),
from: candidate.candidate_id.clone(),
to: None,
cause: "operator: drift on run-9".into(),
rolled_back_at: ts(5_000),
})
.unwrap();
assert_eq!(record.status, CandidateStatus::RolledBack);
}
#[test]
fn gate_admits_in_envelope_and_refuses_out_of_it() {
let envelope = PromotionEnvelope::r08_default();
let candidate = memory_set_candidate(json!({"tone": "warm"}));
let evaluation = clean_evaluation(&candidate, 0.4);
let decision = admit_promotion(&envelope, &candidate, Some(&evaluation), None).unwrap();
assert_eq!(
decision.authority,
PromotionAuthority::Envelope {
envelope_version: "r0.8-default".into()
}
);
let prompt = Candidate::new(
CandidateContent::Prompt {
name: "system".into(),
prompt: "You are careful.".into(),
},
distiller(),
EvidenceSpan::default(),
ts(2_000),
)
.unwrap();
let prompt_eval = clean_evaluation(&prompt, 0.4);
let refused = admit_promotion(&envelope, &prompt, Some(&prompt_eval), None).unwrap_err();
let effect_id = promotion_effect_id(&prompt);
assert_eq!(
refused,
LearnError::Refused(PromotionRefusal::RequiresApproval {
effect_id: effect_id.clone()
})
);
let wrong = ApprovalToken::approve(promotion_effect_id(&candidate), "ops:amjad");
assert!(matches!(
admit_promotion(&envelope, &prompt, Some(&prompt_eval), Some(&wrong)),
Err(LearnError::Refused(
PromotionRefusal::ApprovalMismatch { .. }
))
));
let token = ApprovalToken::approve(effect_id, "ops:amjad");
let decision =
admit_promotion(&envelope, &prompt, Some(&prompt_eval), Some(&token)).unwrap();
assert_eq!(
decision.authority,
PromotionAuthority::Approval {
approved_by: "ops:amjad".into()
}
);
}
#[test]
fn gate_enforces_the_evidence_bar() {
let envelope = PromotionEnvelope::r08_default();
let candidate = memory_set_candidate(json!({}));
let parity = clean_evaluation(&candidate, 0.0);
assert_eq!(
admit_promotion(&envelope, &candidate, Some(&parity), None).unwrap_err(),
LearnError::Refused(PromotionRefusal::InsufficientImprovement {
delta: Some(0.0),
required: 0.0,
})
);
let mut regressed = clean_evaluation(&candidate, 0.4);
regressed.verdict.regressed = true;
assert!(matches!(
admit_promotion(&envelope, &candidate, Some(®ressed), None),
Err(LearnError::Refused(
PromotionRefusal::EvaluationRegressed { .. }
))
));
let mut diverged = clean_evaluation(&candidate, 0.4);
diverged.replay.divergences = vec![ReplayDivergence {
fixture_id: "run-1".into(),
detail: "seq 4: request hash mismatch".into(),
}];
assert!(matches!(
admit_promotion(&envelope, &candidate, Some(&diverged), None),
Err(LearnError::Refused(PromotionRefusal::ReplayDiverged { .. }))
));
let tenant_scoped = Candidate::new(
CandidateContent::MemorySet {
scope: ScopeAddress::new(MemoryScope::Tenant, "default"),
adds: vec![],
supersedes: vec![],
},
distiller(),
EvidenceSpan::default(),
ts(2_000),
)
.unwrap();
let evaluation = clean_evaluation(&tenant_scoped, 0.4);
assert!(matches!(
admit_promotion(&envelope, &tenant_scoped, Some(&evaluation), None),
Err(LearnError::Refused(
PromotionRefusal::ScopeNotAutoPromotable {
scope: MemoryScope::Tenant
}
))
));
assert!(matches!(
admit_promotion(&envelope, &candidate, None, None),
Err(LearnError::Refused(PromotionRefusal::NotEvaluated { .. }))
));
}
#[test]
fn canary_draw_is_deterministic_uniform_and_scoped() {
let candidate = memory_set_candidate(json!({}));
let surface = candidate.surface();
let binding = CanaryBinding {
candidate_id: candidate.candidate_id.clone(),
fraction: 0.25,
};
assert_eq!(
canary_admits(&binding, &surface, "run-7"),
canary_admits(&binding, &surface, "run-7")
);
let full = CanaryBinding {
candidate_id: candidate.candidate_id.clone(),
fraction: 1.0,
};
for run in 0..32 {
assert!(canary_admits(&full, &surface, &format!("run-{run}")));
}
let admitted = (0..1_000)
.filter(|run| canary_admits(&binding, &surface, &format!("run-{run}")))
.count();
assert!(
(150..=350).contains(&admitted),
"fraction 0.25 admitted {admitted}/1000 runs"
);
}
#[test]
fn pointer_moves_on_promotion_and_reponts_on_rollback() {
let a = memory_set_candidate(json!({"v": "a"}));
let b = memory_set_candidate(json!({"v": "b"}));
let pointer = VersionPointer::new(a.surface());
assert_eq!(pointer.active, None);
let promote_a = PromotionReceipt {
candidate_id: a.candidate_id.clone(),
surface: a.surface(),
previous: None,
decision: PromotionDecision {
authority: PromotionAuthority::Envelope {
envelope_version: "r0.8-default".into(),
},
canary: None,
},
promoted_at: ts(4_000),
};
let pointer = pointer.promoted(&promote_a);
assert_eq!(pointer.active, Some(a.candidate_id.clone()));
let promote_b = PromotionReceipt {
candidate_id: b.candidate_id.clone(),
surface: a.surface(),
previous: Some(a.candidate_id.clone()),
decision: promote_a.decision.clone(),
promoted_at: ts(5_000),
};
let pointer = pointer.promoted(&promote_b);
assert_eq!(pointer.active, Some(b.candidate_id.clone()));
let pointer = pointer.rolled_back(&RollbackReceipt {
surface: a.surface(),
from: b.candidate_id.clone(),
to: promote_b.previous.clone(),
cause: "drift".into(),
rolled_back_at: ts(6_000),
});
assert_eq!(pointer.active, Some(a.candidate_id.clone()));
}
#[tokio::test]
async fn overlay_applies_the_candidate_as_a_read_lens() {
let base = Arc::new(InMemoryMemoryStore::new());
let existing = memory_record(json!({"tone": "flat"}));
base.put(&existing).await.unwrap();
let mut added = memory_record(json!({"tone": "warm"}));
added.supersedes = Some(existing.memory_id.clone());
let candidate = Candidate::new(
CandidateContent::MemorySet {
scope: ScopeAddress::new(MemoryScope::Agent, "support-1"),
adds: vec![added.clone()],
supersedes: Vec::new(),
},
distiller(),
EvidenceSpan::default(),
ts(2_000),
)
.unwrap();
let overlay = CandidateOverlay::new(base.clone(), &candidate).unwrap();
assert_eq!(overlay.get(&added.memory_id).await.unwrap(), Some(added));
assert_eq!(
overlay.get(&existing.memory_id).await.unwrap(),
Some(existing.clone())
);
let listed = overlay
.query(&MemoryQuery::default(), Utc::now())
.await
.unwrap();
assert_eq!(listed.len(), 1);
assert!(overlay.put(&existing).await.is_err());
}
}