rusty_agent_runtime/learn.rs
1//! The learning loop's candidate pipeline (R0.8 Rusty Learn, wave 3): the
2//! candidate contract, the evaluation composition seam, the promotion
3//! envelope and its gate, canary binding by seeded draw, and the
4//! active-version pointer with byte-exact rollback.
5//!
6//! The design doc is `docs/learn-design.md` ("The learning loop"). Its
7//! learning rule governs everything here: **no learning process may
8//! silently rewrite a production prompt, graph, policy, memory, or tool
9//! permission.** Learning produces an immutable candidate; the candidate is
10//! evaluated against recorded evidence; promotion is a journaled runtime
11//! transition bounded by a declared envelope; rollback re-points an
12//! immutable version pointer. What a framework does with a config file
13//! edit and a restart, this module does as an evidence-carrying state
14//! transition.
15//!
16//! - [`Candidate`] — the distiller's output: an immutable, versioned,
17//! content-addressed declaration of a proposed change. Identity is
18//! `sha256` over the canonical content ([`derive_candidate_id`]), so two
19//! distillations of the same change converge on one id and a tampered
20//! candidate fails its own address ([`Candidate::verify_address`]).
21//! Closed enum [`CandidateKind`]: `prompt` / `policy` / `memory_set` /
22//! `tool_permission`.
23//! - [`CandidateEvaluation`] — the journaled evaluation payload: the
24//! replay divergence summary, the experiment report pair, the dataset
25//! version, and the comparison verdict. The evaluator itself is a seam
26//! ([`CandidateEvaluator`]), not runtime code — the same boundary open
27//! question 2 draws for distillers, forced by the workspace's dependency
28//! direction: `rusty-eval` links the runtime, never the reverse, so the
29//! runtime owns the journaled *shape* of the evaluation and the
30//! application owns producing it through `rusty-eval`'s
31//! `ExperimentRunner` + `compare()`. [`EvaluationVerdict`] and
32//! [`EvaluationThresholds`] are the deliberate mirrors of `compare()`'s
33//! output and `CompareThresholds` — one serde-pinned record reference,
34//! the same way `rusty-eval` already meets the runtime at the `Journal`.
35//! - [`PromotionEnvelope`] — the declared, per-deployment standing
36//! approval: per candidate kind, what may auto-promote (the evidence
37//! thresholds), what requires a human approval, and what promotes into
38//! a canary. The gate is [`admit_promotion`], a pure function; refusal
39//! is a typed error ([`PromotionRefusal`]), never a silent no-op.
40//! Out-of-envelope promotion requires an
41//! [`crate::effects::ApprovalToken`] scoped to
42//! [`promotion_effect_id`] — derived over the candidate's content hash
43//! and target scope, so an approval for one candidate is
44//! non-transferable to another. This composes the effect kernel rather
45//! than inventing an approval parallel to it.
46//! - [`VersionPointer`] — the active version per surface (prompt name,
47//! policy scope, memory scope, tool grant) as an immutable pointer to a
48//! [`CandidateId`]. Every promotion is a pointer move; rollback
49//! re-points to the previous candidate and is byte-exact because
50//! candidates are content-addressed and immutable — the restored
51//! version is the one that previously served, not a reconstruction.
52//!
53//! Every lifecycle transition (created → evaluated → promoted → rolled
54//! back) journals through four additive [`RunEventKind`](crate::record::RunEventKind) variants —
55//! `CandidateCreated` / `CandidateEvaluated` / `CandidatePromoted` /
56//! `CandidateRolledBack` — the same evolution rule R0.6's `EffectReceipt`
57//! and R0.7's agent variants followed; old journals keep deserializing.
58//! Refused transitions are errors ([`LearnError`]), not silent no-ops.
59//!
60//! Golden-file tests under `tests/golden/` pin every wire shape in this
61//! module; any accidental contract drift fails CI.
62
63use std::collections::HashSet;
64use std::sync::Arc;
65
66use async_trait::async_trait;
67use chrono::{DateTime, Utc};
68use serde::{Deserialize, Serialize};
69use serde_json::Value;
70use sha2::{Digest, Sha256};
71use thiserror::Error;
72
73use crate::effects::{derive_effect_id, ApprovalToken, EffectId};
74use crate::error::{Result, RustyError};
75use crate::journal::JournalSnapshot;
76use crate::memory::{
77 apply_query, MemoryQuery, MemoryRecord, MemoryScope, MemoryStore, ProvenanceAuthor,
78 ScopeAddress,
79};
80use crate::record::{sha256_hex, DecisionFamily, RunManifest};
81
82fn invalid(message: impl Into<String>) -> RustyError {
83 // Candidate construction and application are state updates to the
84 // governed learning plane; contract validation failures reuse the
85 // invalid-update class rather than growing the error taxonomy for one
86 // module (the memory module's own convention).
87 RustyError::InvalidUpdate(message.into())
88}
89
90// --------------------------------------------------------------------- //
91// The candidate contract
92// --------------------------------------------------------------------- //
93
94/// A content-addressed candidate identity: lowercase hex SHA-256 over the
95/// candidate's canonical content ([`derive_candidate_id`]).
96///
97/// Transparent newtype so the type system — not convention — keeps
98/// candidate ids distinct from memory addresses, effect ids, and other
99/// digest strings (the [`PolicyVersion`](crate::record::PolicyVersion) /
100/// [`EffectId`] precedent).
101#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
102#[serde(transparent)]
103pub struct CandidateId(String);
104
105impl CandidateId {
106 /// The hex digest.
107 pub fn as_str(&self) -> &str {
108 &self.0
109 }
110}
111
112impl std::fmt::Display for CandidateId {
113 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
114 f.write_str(&self.0)
115 }
116}
117
118impl From<String> for CandidateId {
119 /// Wrap a digest the caller already trusts — rehydration from storage,
120 /// a rollback receipt's `previous`. Minting ids from content is
121 /// [`derive_candidate_id`]'s job alone; nothing here re-verifies.
122 fn from(digest: String) -> Self {
123 Self(digest)
124 }
125}
126
127/// What a candidate would change. Closed enum — the gate, the pointer,
128/// and the evaluator match exhaustively on it.
129#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
130#[serde(rename_all = "snake_case")]
131pub enum CandidateKind {
132 /// New prompt text for one named prompt.
133 Prompt,
134 /// Executor policy parameters for one decision family.
135 Policy,
136 /// A set of memory records (adds and supersessions).
137 MemorySet,
138 /// A narrowed or widened tool grant.
139 ToolPermission,
140}
141
142/// The direction of a [`CandidateContent::ToolPermission`] change.
143/// Closed enum: the direction is the R0.8 contract — grant mechanics
144/// (which capabilities a narrowed grant drops, how a widened one is
145/// bounded) are R0.9's capsule-manifest work, and this release gates
146/// every tool-permission candidate behind a human approval regardless.
147#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
148#[serde(rename_all = "snake_case")]
149pub enum GrantDirection {
150 /// The grant shrinks (a capability is withdrawn).
151 Narrow,
152 /// The grant grows (a capability is added).
153 Widen,
154}
155
156/// The change a candidate declares, per [`CandidateKind`]. Serialized with
157/// internal tagging (`{"kind": "memory_set", …}`): the kind is part of
158/// the content address — a prompt text and a policy parameter set that
159/// happened to serialize alike must never converge.
160#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
161#[serde(tag = "kind", rename_all = "snake_case")]
162pub enum CandidateContent {
163 /// New prompt text. The text's digest — `sha256_hex` over its UTF-8
164 /// bytes — is exactly the pin [`RunManifest::pin_prompt`] records, so
165 /// the candidate and the run manifest speak one content address.
166 Prompt {
167 /// The prompt's name (the manifest pin's key).
168 name: String,
169 /// The proposed prompt text.
170 prompt: String,
171 },
172 /// Executor policy parameters for one
173 /// [`crate::record::DecisionFamily`] — backoff caps, timeout bounds,
174 /// concurrency limits. The closed legal-action sets stay closed: a
175 /// learned policy chooses among declared actions, never free-form
176 /// outputs.
177 Policy {
178 /// The decision family the parameters govern.
179 family: DecisionFamily,
180 /// The parameter set (schema is the policy registry's, wave 4).
181 parameters: Value,
182 },
183 /// A set of memory records at one scope: adds and supersessions.
184 /// Carrying full [`MemoryRecord`]s — not ids — is what lets the set
185 /// carry wave 2's attributed correction candidates: the records'
186 /// provenance (and therefore their own content addresses) is inside
187 /// this candidate's address.
188 MemorySet {
189 /// The scope the set applies at.
190 scope: ScopeAddress,
191 /// The records the set adds (already content-addressed, already
192 /// immutable — a record in two sets is the same record).
193 adds: Vec<MemoryRecord>,
194 /// Bare memory content addresses the set supersedes beyond the
195 /// adds' own `supersedes` fields.
196 #[serde(default, skip_serializing_if = "Vec::is_empty")]
197 supersedes: Vec<String>,
198 },
199 /// A narrowed or widened tool grant.
200 ToolPermission {
201 /// The tool whose grant changes.
202 tool: String,
203 /// The direction of the change (see [`GrantDirection`]).
204 direction: GrantDirection,
205 },
206}
207
208/// The content address of a candidate: `sha256` over the canonical
209/// serialization of its content — the one hashing primitive shared with
210/// artifact references and journal heads, over the canonical `serde_json`
211/// serialization [`crate::record::PayloadRef::content_hash`] also relies
212/// on (object keys sort deterministically).
213pub fn derive_candidate_id(content: &CandidateContent) -> Result<CandidateId> {
214 Ok(CandidateId(sha256_hex(&serde_json::to_vec(content)?)))
215}
216
217/// The evidence span a distiller read to produce a candidate — journaled
218/// with creation, because a candidate that cannot name its observations
219/// cannot be audited. Every field is optional and absent from the wire
220/// when empty: a hand-authored candidate may carry no span at all, and
221/// sparse evidence must not change the shape for dense readers.
222#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
223pub struct EvidenceSpan {
224 /// The recorded runs whose journals the distiller read. "Completed"
225 /// is load-bearing (the design's observe stage): learning reads
226 /// terminal evidence, never in-flight state.
227 #[serde(default, skip_serializing_if = "Vec::is_empty")]
228 pub run_ids: Vec<String>,
229
230 /// The corrections (R0.8 wave 2) the candidate folds in — the
231 /// reference distiller's input.
232 #[serde(default, skip_serializing_if = "Vec::is_empty")]
233 pub correction_ids: Vec<String>,
234
235 /// The memory records the distiller read (e.g. the attributed
236 /// candidates a `memory_set` carries).
237 #[serde(default, skip_serializing_if = "Vec::is_empty")]
238 pub memory_ids: Vec<String>,
239}
240
241impl EvidenceSpan {
242 /// `true` when no span is carried (the sparse wire shape).
243 pub fn is_empty(&self) -> bool {
244 self.run_ids.is_empty() && self.correction_ids.is_empty() && self.memory_ids.is_empty()
245 }
246}
247
248/// A proposed change: immutable, versioned, content-addressed.
249///
250/// The address covers the **content** — the change itself — and nothing
251/// else: two distillations of the same change converge on one id even
252/// when different distillers read different evidence to reach it (the
253/// design's identity-is-integrity rule). Attribution is not identity, so
254/// the distiller, the evidence span, and the learning instant travel
255/// beside the address rather than inside it — the inverse of
256/// [`MemoryRecord`]'s provenance-in-identity rule, deliberate: a memory
257/// record answers "who claims this," a candidate answers "what would
258/// change."
259///
260/// Immutable by construction: a changed candidate is a new id, and there
261/// is no in-place update anywhere in the pipeline.
262#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
263pub struct Candidate {
264 /// The content address ([`derive_candidate_id`]).
265 pub candidate_id: CandidateId,
266
267 /// The change, per kind.
268 pub content: CandidateContent,
269
270 /// The distiller's identity. Mandatory — journaled with creation
271 /// (`CandidateCreated`), because a candidate that cannot name its
272 /// distiller is indistinguishable from a config edit.
273 pub distilled_by: ProvenanceAuthor,
274
275 /// The evidence span the distiller read. Absent from the wire when
276 /// empty.
277 #[serde(default, skip_serializing_if = "EvidenceSpan::is_empty")]
278 pub evidence: EvidenceSpan,
279
280 /// When the distiller minted the candidate.
281 pub created_at: DateTime<Utc>,
282}
283
284impl Candidate {
285 /// Build a candidate, deriving its content address from `content`.
286 pub fn new(
287 content: CandidateContent,
288 distilled_by: ProvenanceAuthor,
289 evidence: EvidenceSpan,
290 created_at: DateTime<Utc>,
291 ) -> Result<Self> {
292 let candidate_id = derive_candidate_id(&content)?;
293 Ok(Self {
294 candidate_id,
295 content,
296 distilled_by,
297 evidence,
298 created_at,
299 })
300 }
301
302 /// The candidate's kind.
303 pub fn kind(&self) -> CandidateKind {
304 match &self.content {
305 CandidateContent::Prompt { .. } => CandidateKind::Prompt,
306 CandidateContent::Policy { .. } => CandidateKind::Policy,
307 CandidateContent::MemorySet { .. } => CandidateKind::MemorySet,
308 CandidateContent::ToolPermission { .. } => CandidateKind::ToolPermission,
309 }
310 }
311
312 /// The production surface this candidate would change — the pointer
313 /// key: `prompt:{name}` / `policy:{family}` / `memory:{scope}` /
314 /// `tool:{tool}`. One surface admits one active version, which is
315 /// what makes promotion a pointer move and rollback a re-pointing.
316 pub fn surface(&self) -> SurfaceKey {
317 match &self.content {
318 CandidateContent::Prompt { name, .. } => SurfaceKey::new(format!("prompt:{name}")),
319 CandidateContent::Policy { family, .. } => {
320 let family = serde_json::to_value(family)
321 .ok()
322 .and_then(|v| v.as_str().map(str::to_owned))
323 .unwrap_or_else(|| format!("{family:?}").to_lowercase());
324 SurfaceKey::new(format!("policy:{family}"))
325 }
326 CandidateContent::MemorySet { scope, .. } => {
327 SurfaceKey::new(format!("memory:{}", scope.as_address()))
328 }
329 CandidateContent::ToolPermission { tool, .. } => {
330 SurfaceKey::new(format!("tool:{tool}"))
331 }
332 }
333 }
334
335 /// Re-derive the content address and compare: `Ok` when the candidate
336 /// is the one its id names. Identity is integrity — the gate runs
337 /// this before any promotion, so a tampered candidate fails closed at
338 /// the boundary, not after a pointer moved.
339 pub fn verify_address(&self) -> std::result::Result<(), LearnError> {
340 let derived = derive_candidate_id(&self.content)
341 .map_err(|e| LearnError::UnaddressableContent(e.to_string()))?;
342 if derived != self.candidate_id {
343 return Err(LearnError::AddressMismatch {
344 claimed: self.candidate_id.clone(),
345 derived,
346 });
347 }
348 Ok(())
349 }
350
351 /// Apply a `prompt` candidate to a manifest: substitute the named
352 /// prompt's pin with the candidate's — the same digest
353 /// [`RunManifest::pin_prompt`] records, so the evaluation's manifest
354 /// speaks the production surface's content address. Every other kind
355 /// fails: a candidate applies only to the surface its kind declares.
356 pub fn apply_to_manifest(&self, manifest: &mut RunManifest) -> Result<()> {
357 let CandidateContent::Prompt { name, prompt } = &self.content else {
358 return Err(invalid(format!(
359 "only a `prompt` candidate applies to a run manifest; `{}` candidates apply \
360 to their own surfaces",
361 self.kind_str()
362 )));
363 };
364 manifest
365 .prompts
366 .insert(name.clone(), sha256_hex(prompt.as_bytes()));
367 Ok(())
368 }
369
370 fn kind_str(&self) -> &'static str {
371 match self.kind() {
372 CandidateKind::Prompt => "prompt",
373 CandidateKind::Policy => "policy",
374 CandidateKind::MemorySet => "memory_set",
375 CandidateKind::ToolPermission => "tool_permission",
376 }
377 }
378}
379
380/// A candidate's production surface: the pointer key. Transparent newtype
381/// over the canonical `{kind}:{scope}` string ([`Candidate::surface`]).
382#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
383#[serde(transparent)]
384pub struct SurfaceKey(String);
385
386impl SurfaceKey {
387 /// Wrap a surface string (built by [`Candidate::surface`]).
388 pub fn new(surface: impl Into<String>) -> Self {
389 Self(surface.into())
390 }
391
392 /// The surface string.
393 pub fn as_str(&self) -> &str {
394 &self.0
395 }
396}
397
398impl std::fmt::Display for SurfaceKey {
399 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
400 f.write_str(&self.0)
401 }
402}
403
404// --------------------------------------------------------------------- //
405// Effect keys and the approval scope
406// --------------------------------------------------------------------- //
407
408/// The derived idempotency key of a candidate creation:
409/// `candidate:{candidate_id}`. Content addressing makes retried
410/// submissions converge on one key.
411pub fn candidate_effect_key(candidate_id: &CandidateId) -> String {
412 format!("candidate:{candidate_id}")
413}
414
415/// The derived idempotency key of an evaluation:
416/// `evaluation:{candidate_id}:{dataset_version}`. Re-evaluation against
417/// the same dataset version converges; a new dataset version is a new
418/// evaluation by construction.
419pub fn evaluation_effect_key(candidate_id: &CandidateId, dataset_version: &str) -> String {
420 format!("evaluation:{candidate_id}:{dataset_version}")
421}
422
423/// The derived idempotency key of a promotion: `promotion:{candidate_id}`
424/// (the design's mechanism decision). Retried promotions converge, and
425/// recovery re-derives the same key.
426pub fn promotion_effect_key(candidate_id: &CandidateId) -> String {
427 format!("promotion:{candidate_id}")
428}
429
430/// The derived idempotency key of a rollback:
431/// `rollback:{surface}:{candidate_id}` — one rollback per candidate per
432/// surface.
433pub fn rollback_effect_key(surface: &SurfaceKey, candidate_id: &CandidateId) -> String {
434 format!("rollback:{surface}:{candidate_id}")
435}
436
437/// The effect kind promotions derive their deterministic id under.
438pub const PROMOTION_EFFECT_KIND: &str = "candidate_promotion";
439
440/// The deterministic effect id of a candidate's promotion —
441/// [`derive_effect_id`] over the target surface (scope), the promotion
442/// kind, the candidate's content hash (input hash), and the promotion
443/// effect key. This is the id an out-of-envelope [`ApprovalToken`] must
444/// be scoped to: the scope check makes an approval for one candidate
445/// non-transferable to another, and the token's `approved_by` gives the
446/// journaled promotion its attribution.
447pub fn promotion_effect_id(candidate: &Candidate) -> EffectId {
448 derive_effect_id(
449 candidate.surface().as_str(),
450 PROMOTION_EFFECT_KIND,
451 candidate.candidate_id.as_str(),
452 Some(&promotion_effect_key(&candidate.candidate_id)),
453 )
454}
455
456// --------------------------------------------------------------------- //
457// The evaluation composition seam
458// --------------------------------------------------------------------- //
459
460/// The comparison thresholds an evaluation ran under — the deliberate
461/// mirror of `rusty-eval`'s `CompareThresholds`, serde-identical by
462/// contract: the evaluator (which links `rusty-eval`) maps one onto the
463/// other field-for-field, and the journaled payload speaks this shape so
464/// the runtime never links the eval crate (the workspace's dependency
465/// direction is `rusty-eval` → runtime, never the reverse).
466#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
467pub struct EvaluationThresholds {
468 /// Maximum tolerable absolute pass-rate drop, per assertion and per
469 /// case, before the comparison flags a regression.
470 pub max_pass_rate_drop: f64,
471
472 /// Maximum tolerable p95 latency ratio `candidate / baseline`.
473 pub max_latency_p95_ratio: f64,
474}
475
476impl Default for EvaluationThresholds {
477 /// 5-point pass-rate drop tolerance, 25% p95 latency tolerance — the
478 /// same defaults `CompareThresholds` declares.
479 fn default() -> Self {
480 Self {
481 max_pass_rate_drop: 0.05,
482 max_latency_p95_ratio: 1.25,
483 }
484 }
485}
486
487/// The comparison verdict the promotion gate reads — the deliberate
488/// mirror of the release-gate bits of `rusty-eval`'s `ComparisonReport`
489/// (`regressed` plus the target metric's movement), stated in terms the
490/// envelope's evidence thresholds consume: no regression **and**
491/// improvement on the target metric over the named dataset version.
492#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
493pub struct EvaluationVerdict {
494 /// `compare()`'s release-gate bit: any threshold breach.
495 pub regressed: bool,
496
497 /// The metric the envelope's improvement bar reads (e.g.
498 /// `run_pass_rate`, `case:{case_id}`, `assertion:{key}`).
499 pub target_metric: String,
500
501 /// The metric's baseline value, when the baseline names it.
502 #[serde(default, skip_serializing_if = "Option::is_none")]
503 pub baseline: Option<f64>,
504
505 /// The metric's candidate value, when the candidate names it.
506 #[serde(default, skip_serializing_if = "Option::is_none")]
507 pub candidate: Option<f64>,
508
509 /// `candidate - baseline` (negative is worse); absent when either
510 /// side lacks the metric — an improvement bar cannot clear on a
511 /// metric the evidence does not name.
512 #[serde(default, skip_serializing_if = "Option::is_none")]
513 pub delta: Option<f64>,
514}
515
516/// One recorded run that diverged under replay with the candidate
517/// applied: the fixture and the first disagreement, summarized (the full
518/// evidence is the replayed journal, reachable by fixture id).
519#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
520pub struct ReplayDivergence {
521 /// The replay fixture (a recorded run's identity) that diverged.
522 pub fixture_id: String,
523
524 /// The first disagreement, summarized (kind, sequence, request hash —
525 /// enough to locate it without dumping payloads).
526 pub detail: String,
527}
528
529/// The replay half of an evaluation: recorded runs re-driven with the
530/// candidate applied. Exact replay serves journaled effects, so the
531/// candidate's behavior is measured against identical evidence with zero
532/// outbound calls; divergence detection is the replay engine's own
533/// contract, consumed — not re-implemented — here.
534#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
535pub struct ReplaySummary {
536 /// Every fixture re-driven (recorded run identities), sorted for
537 /// determinism.
538 pub fixture_ids: Vec<String>,
539
540 /// How many fixtures replayed without divergence.
541 pub matched: usize,
542
543 /// Every fixture that diverged, sorted by fixture id.
544 #[serde(default, skip_serializing_if = "Vec::is_empty")]
545 pub divergences: Vec<ReplayDivergence>,
546}
547
548impl ReplaySummary {
549 /// `true` when every fixture replayed clean. The auto-promotion bar
550 /// requires it: a candidate that cannot reproduce its evidence has no
551 /// business in front of a comparison verdict.
552 pub fn is_clean(&self) -> bool {
553 self.divergences.is_empty() && self.matched == self.fixture_ids.len()
554 }
555}
556
557/// The journaled evaluation payload — the `CandidateEvaluated` event's
558/// output. The evaluation is evidence, not a log line: the verdict, the
559/// report pair, the dataset version, and the replay fixture ids, so the
560/// improvement is explainable afterward by walking ids (candidate →
561/// evaluation → reports → fixtures).
562#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
563pub struct CandidateEvaluation {
564 /// The evaluated candidate.
565 pub candidate_id: CandidateId,
566
567 /// The versioned dataset both reports ran against. Versioned, never
568 /// edited in place — the envelope's auto-promotion bar may name the
569 /// exact version a clean verdict must come from.
570 pub dataset_version: String,
571
572 /// The replay half: divergence summary plus the fixture ids.
573 pub replay: ReplaySummary,
574
575 /// The baseline experiment report, verbatim (`rusty-eval`'s
576 /// `ExperimentReport` serialized; carried as a value because the
577 /// runtime does not link the eval crate — see the module docs).
578 pub baseline_report: Value,
579
580 /// The candidate experiment report, same convention.
581 pub candidate_report: Value,
582
583 /// The comparison verdict the gate reads.
584 pub verdict: EvaluationVerdict,
585
586 /// The thresholds the comparison applied, echoed so an auditor reads
587 /// the bar the verdict was judged against, not a later default.
588 pub thresholds: EvaluationThresholds,
589
590 /// Who ran the evaluation (attribution is mandatory here too).
591 pub evaluated_by: ProvenanceAuthor,
592
593 /// When the evaluation ran.
594 pub evaluated_at: DateTime<Utc>,
595}
596
597/// What an evaluator is asked to do: run `candidate` over the declared
598/// evidence and produce the journaled [`CandidateEvaluation`].
599/// Wire-complete: the server's evaluate route accepts it as the request
600/// body.
601#[derive(Debug, Clone, Serialize, Deserialize)]
602pub struct EvaluationRequest {
603 /// The dataset version both reports must name.
604 pub dataset_version: String,
605
606 /// The metric the promotion gate reads.
607 pub target_metric: String,
608
609 /// The comparison thresholds.
610 pub thresholds: EvaluationThresholds,
611
612 /// The recorded run journals to re-drive with the candidate applied
613 /// (the replay half's evidence), already integrity-loadable.
614 pub replay_evidence: Vec<JournalSnapshot>,
615}
616
617/// The evaluation seam: composition, not duplication. The implementation
618/// builds `PreparedRun`s with the candidate applied (for `memory_set`,
619/// the candidate's records visible at their scope via
620/// [`CandidateOverlay`]; for `prompt`, the pinned prompt hash substituted
621/// via [`Candidate::apply_to_manifest`]) and drives them through the real
622/// executor — replay over [`EvaluationRequest::replay_evidence`] for the
623/// divergence half, `rusty-eval`'s `ExperimentRunner` over the versioned
624/// dataset for the report half, `compare()` for the verdict.
625///
626/// The runtime owns this trait rather than an implementation for the same
627/// reason it owns the distiller contract but not distillers (design open
628/// question 2), compounded by the workspace's dependency direction:
629/// `rusty-eval` links the runtime, never the reverse. Wave 4's release
630/// proof implements this trait over `rusty-eval`'s public API; wave 3
631/// proves the seam with scripted nodes.
632#[async_trait]
633pub trait CandidateEvaluator: Send + Sync + std::fmt::Debug {
634 /// Evaluate `candidate` against `request`'s evidence. The returned
635 /// evaluation must name the candidate and the request's dataset
636 /// version — the gate refuses mismatches.
637 async fn evaluate(
638 &self,
639 candidate: &Candidate,
640 request: &EvaluationRequest,
641 ) -> Result<CandidateEvaluation>;
642}
643
644// --------------------------------------------------------------------- //
645// Candidate application: the memory overlay
646// --------------------------------------------------------------------- //
647
648/// A `memory_set` candidate applied as a read lens over a live store:
649/// the candidate's records answer at their scope, its supersessions drop
650/// out of default retrieval, and everything else passes through. This is
651/// how evaluation (and, post-promotion, new traffic) sees candidate
652/// memory without a store migration — the candidate applied, as a store.
653///
654/// The lens is deliberately read-only: writes fail. An evaluation that
655/// writes through the candidate's lens would be mutating production
656/// memory mid-measurement — the silent-rewrite pattern the pipeline
657/// exists to forbid.
658#[derive(Debug)]
659pub struct CandidateOverlay {
660 base: Arc<dyn MemoryStore>,
661 adds: Vec<MemoryRecord>,
662 supersedes: HashSet<String>,
663}
664
665impl CandidateOverlay {
666 /// Apply `candidate` over `base`. Fails for non-`memory_set`
667 /// candidates: a candidate applies only to the surface its kind
668 /// declares.
669 pub fn new(base: Arc<dyn MemoryStore>, candidate: &Candidate) -> Result<Self> {
670 let CandidateContent::MemorySet {
671 adds, supersedes, ..
672 } = &candidate.content
673 else {
674 return Err(invalid(format!(
675 "only a `memory_set` candidate applies as a memory overlay; `{}` candidates \
676 apply to their own surfaces",
677 match candidate.kind() {
678 CandidateKind::Prompt => "prompt",
679 CandidateKind::Policy => "policy",
680 CandidateKind::MemorySet => unreachable!(),
681 CandidateKind::ToolPermission => "tool_permission",
682 }
683 )));
684 };
685 Ok(Self {
686 base,
687 adds: adds.clone(),
688 supersedes: supersedes.iter().cloned().collect(),
689 })
690 }
691}
692
693#[async_trait]
694impl MemoryStore for CandidateOverlay {
695 async fn put(&self, _record: &MemoryRecord) -> Result<bool> {
696 Err(invalid(
697 "the candidate overlay is a read lens: writes through it would mutate production \
698 memory mid-evaluation — the silent-rewrite pattern the candidate pipeline exists \
699 to forbid",
700 ))
701 }
702
703 async fn get(&self, memory_id: &str) -> Result<Option<MemoryRecord>> {
704 if let Some(record) = self.adds.iter().find(|r| r.memory_id == memory_id) {
705 return Ok(Some(record.clone()));
706 }
707 self.base.get(memory_id).await
708 }
709
710 async fn all(&self) -> Result<Vec<MemoryRecord>> {
711 // Merge by content address: a candidate record already in the base
712 // is the same record (identity is integrity), so the add wins by
713 // construction and nothing doubles.
714 let mut merged: Vec<MemoryRecord> = self
715 .base
716 .all()
717 .await?
718 .into_iter()
719 .filter(|record| {
720 !self
721 .adds
722 .iter()
723 .any(|add| add.memory_id == record.memory_id)
724 })
725 .collect();
726 merged.extend(self.adds.iter().cloned());
727 Ok(merged)
728 }
729
730 async fn remove(&self, _memory_id: &str) -> Result<bool> {
731 Err(invalid(
732 "the candidate overlay is a read lens: deletion through it would mutate production \
733 memory mid-evaluation",
734 ))
735 }
736
737 async fn query(&self, query: &MemoryQuery, now: DateTime<Utc>) -> Result<Vec<MemoryRecord>> {
738 // Core's matcher supplies every filter semantic, including the
739 // superseded set it computes from the merged universe (the adds'
740 // own `supersedes` fields included). The candidate's explicit
741 // supersession list is the overlay's own contribution: drop those
742 // ids unless the query asked for superseded records.
743 let matched = apply_query(&self.all().await?, query, now);
744 if query.include_superseded || self.supersedes.is_empty() {
745 return Ok(matched);
746 }
747 Ok(matched
748 .into_iter()
749 .filter(|record| !self.supersedes.contains(&record.memory_id))
750 .collect())
751 }
752}
753
754// --------------------------------------------------------------------- //
755// The promotion envelope and its gate
756// --------------------------------------------------------------------- //
757
758/// The evidence thresholds an auto-promotion must clear (the design's
759/// rule): a clean replay, `compare()` showing no regression, **and**
760/// improvement on the target metric — over the named dataset version,
761/// when the deployment names one.
762#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
763pub struct AutoPromotion {
764 /// The dataset version a clean verdict must come from. `None` accepts
765 /// the verdict's own version — honest for deployments that version
766 /// datasets per evaluation; a named version pins the promotion to the
767 /// exact evidence the deployment reviewed.
768 #[serde(default, skip_serializing_if = "Option::is_none")]
769 pub dataset_version: Option<String>,
770
771 /// The target-metric delta must exceed this (strictly). `0.0` is the
772 /// design's default: any improvement clears, parity does not.
773 pub min_improvement: f64,
774
775 /// The memory scopes a `memory_set` candidate may auto-promote at
776 /// (ignored for other kinds; empty = unrestricted). The R0.8 default
777 /// names `run` and `agent` (open question 6): wider scopes always
778 /// require a human approval this release.
779 #[serde(default, skip_serializing_if = "Vec::is_empty")]
780 pub scopes: Vec<MemoryScope>,
781}
782
783/// What the envelope declares for one candidate kind. Closed enum — the
784/// gate matches exhaustively.
785#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
786#[serde(tag = "mode", rename_all = "snake_case")]
787pub enum EnvelopeRule {
788 /// May auto-promote when the evaluation clears the declared evidence
789 /// thresholds. Inside the envelope, the envelope itself is the
790 /// standing approval — versioned and declared, not a silent default.
791 Auto(AutoPromotion),
792
793 /// Always requires a human [`ApprovalToken`] scoped to
794 /// [`promotion_effect_id`], whatever the evidence says. The token's
795 /// `approved_by` is the promotion's attribution.
796 Approval,
797
798 /// Auto-promotes into a canary: the candidate binds to the declared
799 /// fraction of new runs (admission picks by seeded draw —
800 /// [`canary_admits`] — so a recorded run reproduces its assignment),
801 /// the static version serving the rest. The evidence thresholds gate
802 /// entry into the canary, exactly as for [`EnvelopeRule::Auto`].
803 Canary {
804 /// The fraction of new runs the candidate serves, in `(0, 1]`.
805 fraction: f64,
806 /// The evidence thresholds gating canary entry.
807 auto: AutoPromotion,
808 },
809}
810
811/// The declared, per-deployment promotion envelope: per candidate kind,
812/// what may promote automatically, what requires review, and what
813/// canaries. Versioned (`envelope_version`) because the envelope is the
814/// standing approval — a journaled promotion names the envelope version
815/// it cleared, so the audit reads the declaration that was in force, not
816/// a later edit.
817#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
818pub struct PromotionEnvelope {
819 /// The deployment-declared envelope version.
820 pub envelope_version: String,
821
822 /// The rule for `prompt` candidates.
823 pub prompt: EnvelopeRule,
824
825 /// The rule for `policy` candidates.
826 pub policy: EnvelopeRule,
827
828 /// The rule for `memory_set` candidates.
829 pub memory_set: EnvelopeRule,
830
831 /// The rule for `tool_permission` candidates.
832 pub tool_permission: EnvelopeRule,
833}
834
835impl PromotionEnvelope {
836 /// The R0.8 default (design open question 6): `memory_set` candidates
837 /// at run and agent scope with a clean verdict may auto-promote;
838 /// `prompt`, `policy`, and `tool_permission` always require an
839 /// approval token this release.
840 pub fn r08_default() -> Self {
841 Self {
842 envelope_version: "r0.8-default".to_owned(),
843 prompt: EnvelopeRule::Approval,
844 policy: EnvelopeRule::Approval,
845 memory_set: EnvelopeRule::Auto(AutoPromotion {
846 dataset_version: None,
847 min_improvement: 0.0,
848 scopes: vec![MemoryScope::Run, MemoryScope::Agent],
849 }),
850 tool_permission: EnvelopeRule::Approval,
851 }
852 }
853
854 /// The rule for `kind`.
855 pub fn rule_for(&self, kind: CandidateKind) -> &EnvelopeRule {
856 match kind {
857 CandidateKind::Prompt => &self.prompt,
858 CandidateKind::Policy => &self.policy,
859 CandidateKind::MemorySet => &self.memory_set,
860 CandidateKind::ToolPermission => &self.tool_permission,
861 }
862 }
863
864 /// The declaration's own validity: canary fractions in `(0, 1]` and
865 /// improvement bars non-negative. Checked where envelopes are
866 /// declared (deployment configuration), so a malformed envelope fails
867 /// at startup, not at a promotion.
868 pub fn validate(&self) -> Result<()> {
869 for rule in [
870 &self.prompt,
871 &self.policy,
872 &self.memory_set,
873 &self.tool_permission,
874 ] {
875 match rule {
876 EnvelopeRule::Auto(auto) => check_auto(auto)?,
877 EnvelopeRule::Canary { fraction, auto } => {
878 if !(fraction.is_finite() && *fraction > 0.0 && *fraction <= 1.0) {
879 return Err(invalid(format!(
880 "canary fraction must be in (0, 1], got {fraction} — a fraction \
881 outside the interval binds nothing or everything, and both are \
882 silent full promotions or silent no-ops"
883 )));
884 }
885 check_auto(auto)?;
886 }
887 EnvelopeRule::Approval => {}
888 }
889 }
890 Ok(())
891 }
892}
893
894fn check_auto(auto: &AutoPromotion) -> Result<()> {
895 if !(auto.min_improvement.is_finite() && auto.min_improvement >= 0.0) {
896 return Err(invalid(format!(
897 "min_improvement must be finite and non-negative, got {} — a negative bar would \
898 auto-promote regressions, which is the one outcome the gate exists to refuse",
899 auto.min_improvement
900 )));
901 }
902 Ok(())
903}
904
905/// A canary binding: the candidate serves `fraction` of new runs on its
906/// surface, admission picking by seeded draw ([`canary_admits`]); the
907/// static version (or the pointer's full `active`) serves the rest.
908#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
909pub struct CanaryBinding {
910 /// The canaried candidate.
911 pub candidate_id: CandidateId,
912
913 /// The fraction of new runs the candidate serves, in `(0, 1]`.
914 pub fraction: f64,
915}
916
917/// Domain-separation prefix for [`canary_admits`] — canary draws must
918/// never collide with effect ids, journal heads, or any other digest in
919/// the system.
920pub const CANARY_DRAW_DOMAIN: &str = "rusty/canary-draw/v1";
921
922/// The canary admission draw: whether `run_id` binds `binding`'s
923/// candidate on `surface`.
924///
925/// **Seed derivation, documented (the design's reproducibility rule).**
926/// The draw is `SHA-256` over the newline-joined tuple
927/// `CANARY_DRAW_DOMAIN "\n" surface "\n" candidate_id "\n" run_id`,
928/// read as a `u64` from the digest's first eight bytes (big-endian) and
929/// compared against `fraction × u64::MAX`. Every input is journaled
930/// evidence — the surface and candidate id are on the pointer the run
931/// bound, the run id is the journal's own identity — so a recorded run
932/// re-derives its assignment exactly, and the draw needs no RNG state of
933/// its own. The candidate id's presence makes two canaries on one
934/// surface independent draws; the run id's presence makes one canary's
935/// assignments uniform across traffic.
936pub fn canary_admits(binding: &CanaryBinding, surface: &SurfaceKey, run_id: &str) -> bool {
937 if binding.fraction >= 1.0 {
938 return true;
939 }
940 let material = [
941 CANARY_DRAW_DOMAIN,
942 surface.as_str(),
943 binding.candidate_id.as_str(),
944 run_id,
945 ]
946 .join("\n");
947 // The first eight bytes of the digest as a big-endian u64: uniform
948 // over the digest space, so `draw < fraction × MAX` admits a
949 // `fraction` share of runs.
950 let mut hasher = Sha256::new();
951 hasher.update(material.as_bytes());
952 let digest = hasher.finalize();
953 let draw = u64::from_be_bytes(digest[..8].try_into().expect("eight bytes"));
954 (draw as f64) < binding.fraction * (u64::MAX as f64)
955}
956
957/// Why a promotion was refused. A dedicated error type (the
958/// [`crate::effects::EffectViolation`] precedent): refusals are contract
959/// outcomes surfaced to the caller, not runtime failures — and a refused
960/// promotion changes nothing.
961#[derive(Debug, Clone, PartialEq, Error)]
962pub enum PromotionRefusal {
963 /// The candidate was never evaluated. Promotion is gated on evidence;
964 /// there is no evidence-free path, not even with an approval — a
965 /// human approves *reviewed evidence*, never a blank check.
966 #[error(
967 "candidate `{candidate_id}` has no journaled evaluation: promotion is gated on \
968 evidence — a human approves reviewed evidence, never a blank check"
969 )]
970 NotEvaluated {
971 /// The candidate refused.
972 candidate_id: CandidateId,
973 },
974
975 /// The evaluation on record is not this candidate's.
976 #[error(
977 "evaluation names candidate `{evaluation}` but promotion was requested for \
978 `{candidate_id}` — the evidence must be the candidate's own"
979 )]
980 EvaluationMismatch {
981 /// The candidate refused.
982 candidate_id: CandidateId,
983 /// The candidate the journaled evaluation names.
984 evaluation: CandidateId,
985 },
986
987 /// The replay half diverged: the candidate could not reproduce its
988 /// recorded evidence.
989 #[error(
990 "candidate `{candidate_id}` diverged under replay ({divergences} fixture(s)): a \
991 candidate that cannot reproduce its evidence never auto-promotes"
992 )]
993 ReplayDiverged {
994 /// The candidate refused.
995 candidate_id: CandidateId,
996 /// How many fixtures diverged.
997 divergences: usize,
998 },
999
1000 /// `compare()` flagged a regression beyond the declared thresholds.
1001 #[error(
1002 "candidate `{candidate_id}` regressed against its baseline: the auto-promotion bar \
1003 is no regression AND improvement — the evidence failed the first half"
1004 )]
1005 EvaluationRegressed {
1006 /// The candidate refused.
1007 candidate_id: CandidateId,
1008 },
1009
1010 /// The envelope names a dataset version the evaluation did not run.
1011 #[error(
1012 "envelope requires a clean verdict over dataset `{required}` but the evaluation \
1013 ran `{evaluated}` — the promotion bar names its evidence exactly"
1014 )]
1015 DatasetVersionMismatch {
1016 /// The version the envelope names.
1017 required: String,
1018 /// The version the evaluation ran.
1019 evaluated: String,
1020 },
1021
1022 /// A `memory_set` candidate at a scope the auto rule does not cover.
1023 #[error(
1024 "memory_set candidates at `{scope:?}` scope do not auto-promote under this envelope — \
1025 the R0.8 default covers run and agent scope; wider scopes require an approval"
1026 )]
1027 ScopeNotAutoPromotable {
1028 /// The scope that fell outside the rule.
1029 scope: MemoryScope,
1030 },
1031
1032 /// The target metric did not improve past the declared bar.
1033 #[error(
1034 "target metric moved by {delta:?} but the envelope requires improvement past \
1035 {required} — parity is not improvement, and the auto bar does not clear on it"
1036 )]
1037 InsufficientImprovement {
1038 /// The observed delta (`None`: the evidence did not name the
1039 /// metric at all).
1040 delta: Option<f64>,
1041 /// The bar the envelope declared.
1042 required: f64,
1043 },
1044
1045 /// The candidate falls outside the envelope's auto paths: a human
1046 /// approval scoped to the named effect id is required.
1047 #[error(
1048 "this promotion is outside the envelope: present an approval token scoped to \
1049 effect id {effect_id} — the scope check makes an approval for one candidate \
1050 non-transferable to another"
1051 )]
1052 RequiresApproval {
1053 /// The effect id the approval must be scoped to
1054 /// ([`promotion_effect_id`]).
1055 effect_id: EffectId,
1056 },
1057
1058 /// A token was presented, but it approves a different effect id.
1059 #[error(
1060 "approval token for {presented} does not admit this promotion ({required}) — an \
1061 approval is scoped to exactly one candidate's promotion and is not transferable"
1062 )]
1063 ApprovalMismatch {
1064 /// The effect id the admission requires.
1065 required: EffectId,
1066 /// The effect id the presented token approves.
1067 presented: EffectId,
1068 },
1069}
1070
1071/// The learn plane's typed errors: address integrity, lifecycle
1072/// transitions, and promotion refusals. Refused operations change
1073/// nothing — there is no silent no-op anywhere in the pipeline.
1074#[derive(Debug, Clone, PartialEq, Error)]
1075pub enum LearnError {
1076 /// A candidate's id does not re-derive from its content — the
1077 /// tampered-candidate case, failing closed at the gate.
1078 #[error(
1079 "candidate address mismatch: id {claimed} does not re-derive from the content \
1080 (derived {derived}) — identity is integrity, and a tampered candidate fails its \
1081 own address"
1082 )]
1083 AddressMismatch {
1084 /// The id the candidate claims.
1085 claimed: CandidateId,
1086 /// The id its content derives.
1087 derived: CandidateId,
1088 },
1089
1090 /// The candidate's content could not be serialized for addressing —
1091 /// unreachable for well-formed content, surfaced rather than
1092 /// panicked.
1093 #[error("candidate content could not be addressed: {0}")]
1094 UnaddressableContent(String),
1095
1096 /// A lifecycle transition the state machine does not admit (e.g.
1097 /// promoting a candidate that was never evaluated, rolling back one
1098 /// that was never promoted).
1099 #[error(
1100 "invalid candidate transition: cannot {action} from status `{from:?}` — refused \
1101 transitions are errors, not silent no-ops"
1102 )]
1103 InvalidTransition {
1104 /// The status the transition was attempted from.
1105 from: CandidateStatus,
1106 /// The attempted transition.
1107 action: &'static str,
1108 },
1109
1110 /// A receipt presented for one candidate names another.
1111 #[error(
1112 "receipt names candidate `{named}` but the record is `{candidate_id}` — a receipt \
1113 applies to the candidate it was minted for, never to another"
1114 )]
1115 ReceiptMismatch {
1116 /// The candidate the record holds.
1117 candidate_id: CandidateId,
1118 /// The candidate the receipt names.
1119 named: CandidateId,
1120 },
1121
1122 /// The promotion gate refused.
1123 #[error("{0}")]
1124 Refused(#[from] PromotionRefusal),
1125}
1126
1127/// The promotion gate's positive decision: the authority the promotion
1128/// clears under, journaled on the receipt — the envelope version (the
1129/// standing approval) or the token's `approved_by` — plus the canary
1130/// binding, when the promotion is a canary.
1131#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1132pub struct PromotionDecision {
1133 /// Who authorized the promotion.
1134 pub authority: PromotionAuthority,
1135
1136 /// The canary binding, when the envelope declared a canary.
1137 #[serde(default, skip_serializing_if = "Option::is_none")]
1138 pub canary: Option<CanaryBinding>,
1139}
1140
1141/// The authority a promotion cleared under. Closed enum — the journaled
1142/// attribution.
1143#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1144#[serde(tag = "authority", rename_all = "snake_case")]
1145pub enum PromotionAuthority {
1146 /// The envelope's auto path cleared: the envelope itself is the
1147 /// standing approval, and the journaled version is the declaration
1148 /// that was in force.
1149 Envelope {
1150 /// The envelope version that admitted the promotion.
1151 envelope_version: String,
1152 },
1153 /// A human approved out-of-envelope: the token's `approved_by` is the
1154 /// attribution.
1155 Approval {
1156 /// Who approved (the token's `approved_by`).
1157 approved_by: String,
1158 },
1159}
1160
1161/// The promotion gate (the design's promote stage), a pure function over
1162/// the envelope, the candidate, its journaled evaluation, and an optional
1163/// approval token.
1164///
1165/// Order of decisions: integrity first ([`Candidate::verify_address`] —
1166/// a tampered candidate fails closed before any policy reads it), then
1167/// evidence (a journaled evaluation of *this* candidate must exist —
1168/// approvals review evidence, they never replace it), then the envelope
1169/// rule for the candidate's kind: auto paths check the evidence
1170/// thresholds (clean replay, no regression, improvement past the
1171/// declared bar, over the named dataset version, at an admitted scope),
1172/// the approval path requires a token scoped to [`promotion_effect_id`].
1173/// Refusal is a typed [`PromotionRefusal`]; nothing here mutates
1174/// anything.
1175pub fn admit_promotion(
1176 envelope: &PromotionEnvelope,
1177 candidate: &Candidate,
1178 evaluation: Option<&CandidateEvaluation>,
1179 approval: Option<&ApprovalToken>,
1180) -> std::result::Result<PromotionDecision, LearnError> {
1181 candidate.verify_address()?;
1182 let evaluation = evaluation.ok_or(PromotionRefusal::NotEvaluated {
1183 candidate_id: candidate.candidate_id.clone(),
1184 })?;
1185 if evaluation.candidate_id != candidate.candidate_id {
1186 return Err(PromotionRefusal::EvaluationMismatch {
1187 candidate_id: candidate.candidate_id.clone(),
1188 evaluation: evaluation.candidate_id.clone(),
1189 }
1190 .into());
1191 }
1192 match envelope.rule_for(candidate.kind()) {
1193 EnvelopeRule::Auto(auto) => {
1194 check_evidence_bar(auto, candidate, evaluation)?;
1195 Ok(PromotionDecision {
1196 authority: PromotionAuthority::Envelope {
1197 envelope_version: envelope.envelope_version.clone(),
1198 },
1199 canary: None,
1200 })
1201 }
1202 EnvelopeRule::Canary { fraction, auto } => {
1203 check_evidence_bar(auto, candidate, evaluation)?;
1204 Ok(PromotionDecision {
1205 authority: PromotionAuthority::Envelope {
1206 envelope_version: envelope.envelope_version.clone(),
1207 },
1208 canary: Some(CanaryBinding {
1209 candidate_id: candidate.candidate_id.clone(),
1210 fraction: *fraction,
1211 }),
1212 })
1213 }
1214 EnvelopeRule::Approval => {
1215 let required = promotion_effect_id(candidate);
1216 let token = approval.ok_or(PromotionRefusal::RequiresApproval {
1217 effect_id: required.clone(),
1218 })?;
1219 if !token.admits(&required) {
1220 return Err(PromotionRefusal::ApprovalMismatch {
1221 required,
1222 presented: token.effect_id().clone(),
1223 }
1224 .into());
1225 }
1226 Ok(PromotionDecision {
1227 authority: PromotionAuthority::Approval {
1228 approved_by: token.approved_by().to_owned(),
1229 },
1230 canary: None,
1231 })
1232 }
1233 }
1234}
1235
1236/// The auto paths' evidence bar (the design's thresholds): clean replay,
1237/// no regression, improvement past the declared bar on the target
1238/// metric, over the named dataset version, at an admitted scope.
1239fn check_evidence_bar(
1240 auto: &AutoPromotion,
1241 candidate: &Candidate,
1242 evaluation: &CandidateEvaluation,
1243) -> std::result::Result<(), LearnError> {
1244 if !evaluation.replay.is_clean() {
1245 return Err(PromotionRefusal::ReplayDiverged {
1246 candidate_id: candidate.candidate_id.clone(),
1247 divergences: evaluation.replay.divergences.len(),
1248 }
1249 .into());
1250 }
1251 if evaluation.verdict.regressed {
1252 return Err(PromotionRefusal::EvaluationRegressed {
1253 candidate_id: candidate.candidate_id.clone(),
1254 }
1255 .into());
1256 }
1257 if let Some(required) = &auto.dataset_version {
1258 if required != &evaluation.dataset_version {
1259 return Err(PromotionRefusal::DatasetVersionMismatch {
1260 required: required.clone(),
1261 evaluated: evaluation.dataset_version.clone(),
1262 }
1263 .into());
1264 }
1265 }
1266 if let CandidateContent::MemorySet { scope, .. } = &candidate.content {
1267 if !auto.scopes.is_empty() && !auto.scopes.contains(&scope.scope) {
1268 return Err(PromotionRefusal::ScopeNotAutoPromotable { scope: scope.scope }.into());
1269 }
1270 }
1271 let clears = evaluation
1272 .verdict
1273 .delta
1274 .is_some_and(|delta| delta > auto.min_improvement);
1275 if !clears {
1276 return Err(PromotionRefusal::InsufficientImprovement {
1277 delta: evaluation.verdict.delta,
1278 required: auto.min_improvement,
1279 }
1280 .into());
1281 }
1282 Ok(())
1283}
1284
1285// --------------------------------------------------------------------- //
1286// The lifecycle record and the active-version pointer
1287// --------------------------------------------------------------------- //
1288
1289/// Where a candidate is in its lifecycle. Closed enum; transitions are
1290/// journaled events, and refused transitions are errors.
1291#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
1292#[serde(rename_all = "snake_case")]
1293pub enum CandidateStatus {
1294 /// Distilled, not yet evaluated.
1295 Created,
1296 /// Evaluated against recorded evidence; the evaluation is on record.
1297 Evaluated,
1298 /// Promoted: the surface's pointer names this candidate (fully, or as
1299 /// the canary).
1300 Promoted,
1301 /// Rolled back: the pointer re-pointed away from this candidate.
1302 RolledBack,
1303}
1304
1305/// The journaled promotion receipt — the `CandidatePromoted` event's
1306/// output payload. Plays the effect receipt's role for the learning
1307/// plane: the durable, attributable confirmation that the pointer moved.
1308#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1309pub struct PromotionReceipt {
1310 /// The promoted candidate.
1311 pub candidate_id: CandidateId,
1312
1313 /// The surface whose pointer moved.
1314 pub surface: SurfaceKey,
1315
1316 /// The pointer's full-traffic value before the move (`None`: the
1317 /// static version served). Rollback re-points to exactly this — the
1318 /// byte-exactness comes from candidates being content-addressed and
1319 /// immutable, so `previous` *is* the version that served, not a
1320 /// reconstruction of it.
1321 #[serde(default, skip_serializing_if = "Option::is_none")]
1322 pub previous: Option<CandidateId>,
1323
1324 /// The gate's decision: the authority and the canary binding.
1325 pub decision: PromotionDecision,
1326
1327 /// When the promotion executed.
1328 pub promoted_at: DateTime<Utc>,
1329}
1330
1331/// The journaled rollback receipt — the `CandidateRolledBack` event's
1332/// output payload.
1333#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1334pub struct RollbackReceipt {
1335 /// The surface whose pointer re-pointed.
1336 pub surface: SurfaceKey,
1337
1338 /// The candidate rolled back (the version that was serving).
1339 pub from: CandidateId,
1340
1341 /// The candidate re-pointed to (`None`: the static version serves
1342 /// again — revert-to-default is always a legal rollback).
1343 #[serde(default, skip_serializing_if = "Option::is_none")]
1344 pub to: Option<CandidateId>,
1345
1346 /// The causing evidence: what prompted the rollback (a drift
1347 /// observation's journal ids, an operator's statement naming the
1348 /// evidence). Free text by design — wave 4's drift monitor will
1349 /// write it with the same shape operators use now.
1350 pub cause: String,
1351
1352 /// When the rollback executed.
1353 pub rolled_back_at: DateTime<Utc>,
1354}
1355
1356/// A candidate and its lifecycle state: the store row both server
1357/// backends persist. Transitions go through the `apply_*` methods, which
1358/// enforce the state machine (created → evaluated → promoted → rolled
1359/// back) and refuse everything else as a typed error — the store trusts
1360/// what the gate admitted, exactly as the memory store trusts the write
1361/// gate.
1362#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1363pub struct CandidateRecord {
1364 /// The candidate itself (immutable).
1365 pub candidate: Candidate,
1366
1367 /// Where it is in its lifecycle.
1368 pub status: CandidateStatus,
1369
1370 /// The journaled evaluation (set on evaluate; replaced on
1371 /// re-evaluation — a new dataset version is a new evaluation).
1372 #[serde(default, skip_serializing_if = "Option::is_none")]
1373 pub evaluation: Option<CandidateEvaluation>,
1374
1375 /// The journaled promotion receipt (set on promote).
1376 #[serde(default, skip_serializing_if = "Option::is_none")]
1377 pub promotion: Option<PromotionReceipt>,
1378
1379 /// The journaled rollback receipt (set on rollback).
1380 #[serde(default, skip_serializing_if = "Option::is_none")]
1381 pub rollback: Option<RollbackReceipt>,
1382}
1383
1384impl CandidateRecord {
1385 /// A freshly created candidate.
1386 pub fn new(candidate: Candidate) -> Self {
1387 Self {
1388 candidate,
1389 status: CandidateStatus::Created,
1390 evaluation: None,
1391 promotion: None,
1392 rollback: None,
1393 }
1394 }
1395
1396 /// The candidate's id.
1397 pub fn candidate_id(&self) -> &CandidateId {
1398 &self.candidate.candidate_id
1399 }
1400
1401 /// Record an evaluation: `created → evaluated`, or `evaluated →
1402 /// evaluated` for re-evaluation (a new dataset version is a new
1403 /// evaluation; the effect key names both). Refused from `promoted`
1404 /// and `rolled_back`: re-evaluating a settled candidate reads as a
1405 /// new distillation, and the model keeps that honest by requiring
1406 /// one.
1407 pub fn apply_evaluation(
1408 &mut self,
1409 evaluation: CandidateEvaluation,
1410 ) -> std::result::Result<(), LearnError> {
1411 match self.status {
1412 CandidateStatus::Created | CandidateStatus::Evaluated => {}
1413 other => {
1414 return Err(LearnError::InvalidTransition {
1415 from: other,
1416 action: "evaluate",
1417 })
1418 }
1419 }
1420 if evaluation.candidate_id != self.candidate.candidate_id {
1421 return Err(PromotionRefusal::EvaluationMismatch {
1422 candidate_id: self.candidate.candidate_id.clone(),
1423 evaluation: evaluation.candidate_id,
1424 }
1425 .into());
1426 }
1427 self.evaluation = Some(evaluation);
1428 self.status = CandidateStatus::Evaluated;
1429 Ok(())
1430 }
1431
1432 /// Record a promotion: `evaluated → promoted`. The gate
1433 /// ([`admit_promotion`]) must already have cleared — this method
1434 /// enforces the state machine, not the evidence bar.
1435 pub fn apply_promotion(
1436 &mut self,
1437 receipt: PromotionReceipt,
1438 ) -> std::result::Result<(), LearnError> {
1439 if self.status != CandidateStatus::Evaluated {
1440 return Err(LearnError::InvalidTransition {
1441 from: self.status,
1442 action: "promote",
1443 });
1444 }
1445 if receipt.candidate_id != self.candidate.candidate_id {
1446 return Err(LearnError::ReceiptMismatch {
1447 candidate_id: self.candidate.candidate_id.clone(),
1448 named: receipt.candidate_id,
1449 });
1450 }
1451 self.promotion = Some(receipt);
1452 self.status = CandidateStatus::Promoted;
1453 Ok(())
1454 }
1455
1456 /// Record a rollback: `promoted → rolled_back`.
1457 pub fn apply_rollback(
1458 &mut self,
1459 receipt: RollbackReceipt,
1460 ) -> std::result::Result<(), LearnError> {
1461 if self.status != CandidateStatus::Promoted {
1462 return Err(LearnError::InvalidTransition {
1463 from: self.status,
1464 action: "roll back",
1465 });
1466 }
1467 if receipt.from != self.candidate.candidate_id {
1468 return Err(LearnError::ReceiptMismatch {
1469 candidate_id: self.candidate.candidate_id.clone(),
1470 named: receipt.from,
1471 });
1472 }
1473 self.rollback = Some(receipt);
1474 self.status = CandidateStatus::RolledBack;
1475 Ok(())
1476 }
1477}
1478
1479/// The active version of one production surface: an immutable-pointer
1480/// move away from any version that ever served.
1481///
1482/// Two slots, exactly the design's canary shape: `active` is the
1483/// full-traffic version (`None` — the static version serves, the
1484/// documented floor); `canary` binds one candidate to a declared fraction
1485/// of new runs while `active` serves the rest. New runs bind the pointer
1486/// at admission (the canary by seeded draw — [`canary_admits`]);
1487/// in-flight runs keep the version their checkpoint header pins, the same
1488/// conservatism as worker-version pinning and manifest pinning.
1489#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1490pub struct VersionPointer {
1491 /// The surface this pointer governs.
1492 pub surface: SurfaceKey,
1493
1494 /// The full-traffic candidate (`None`: the static version serves).
1495 #[serde(default, skip_serializing_if = "Option::is_none")]
1496 pub active: Option<CandidateId>,
1497
1498 /// The canary binding, when one is declared.
1499 #[serde(default, skip_serializing_if = "Option::is_none")]
1500 pub canary: Option<CanaryBinding>,
1501}
1502
1503impl VersionPointer {
1504 /// A pointer with nothing promoted: the static version serves.
1505 pub fn new(surface: SurfaceKey) -> Self {
1506 Self {
1507 surface,
1508 active: None,
1509 canary: None,
1510 }
1511 }
1512
1513 /// The pointer after a promotion: a canary promotion binds the
1514 /// candidate to its fraction (the full-traffic version keeps serving
1515 /// the rest); a full promotion moves `active` and clears any canary —
1516 /// a full promotion supersedes the experiment it graduated from.
1517 pub fn promoted(&self, receipt: &PromotionReceipt) -> VersionPointer {
1518 let mut next = self.clone();
1519 if let Some(binding) = &receipt.decision.canary {
1520 next.canary = Some(binding.clone());
1521 } else {
1522 next.active = Some(receipt.candidate_id.clone());
1523 next.canary = None;
1524 }
1525 next
1526 }
1527
1528 /// The pointer after a rollback: rolling back the full-traffic
1529 /// version re-points `active` to the receipt's `to`; rolling back the
1530 /// canary clears the binding. The caller validates that `from` is the
1531 /// serving version before building the receipt — this is the move,
1532 /// not the check.
1533 pub fn rolled_back(&self, receipt: &RollbackReceipt) -> VersionPointer {
1534 let mut next = self.clone();
1535 if self.active.as_ref() == Some(&receipt.from) {
1536 next.active = receipt.to.clone();
1537 }
1538 if self
1539 .canary
1540 .as_ref()
1541 .is_some_and(|binding| binding.candidate_id == receipt.from)
1542 {
1543 next.canary = None;
1544 }
1545 next
1546 }
1547}
1548
1549#[cfg(test)]
1550mod tests {
1551 use super::*;
1552 use crate::memory::{InMemoryMemoryStore, MemoryKind, MemoryProvenance, ValidityWindow};
1553 use serde_json::json;
1554
1555 fn ts(millis: i64) -> DateTime<Utc> {
1556 DateTime::<Utc>::from_timestamp_millis(millis).unwrap()
1557 }
1558
1559 fn distiller() -> ProvenanceAuthor {
1560 ProvenanceAuthor::Distiller {
1561 name: "correction-loop".into(),
1562 }
1563 }
1564
1565 fn memory_record(content: Value) -> MemoryRecord {
1566 MemoryRecord::new(
1567 MemoryKind::Fact,
1568 ScopeAddress::new(MemoryScope::Agent, "support-1"),
1569 MemoryProvenance {
1570 author: ProvenanceAuthor::Human {
1571 human_id: "amjad".into(),
1572 },
1573 evidence: Default::default(),
1574 written_at: ts(1_000),
1575 },
1576 1.0,
1577 ValidityWindow::starting(ts(500)),
1578 ts(1_000),
1579 content,
1580 )
1581 .unwrap()
1582 }
1583
1584 fn memory_set_candidate(content: Value) -> Candidate {
1585 Candidate::new(
1586 CandidateContent::MemorySet {
1587 scope: ScopeAddress::new(MemoryScope::Agent, "support-1"),
1588 adds: vec![memory_record(content)],
1589 supersedes: Vec::new(),
1590 },
1591 distiller(),
1592 EvidenceSpan {
1593 run_ids: vec!["run-1".into()],
1594 ..EvidenceSpan::default()
1595 },
1596 ts(2_000),
1597 )
1598 .unwrap()
1599 }
1600
1601 fn clean_evaluation(candidate: &Candidate, delta: f64) -> CandidateEvaluation {
1602 CandidateEvaluation {
1603 candidate_id: candidate.candidate_id.clone(),
1604 dataset_version: "v3".into(),
1605 replay: ReplaySummary {
1606 fixture_ids: vec!["run-1".into()],
1607 matched: 1,
1608 divergences: Vec::new(),
1609 },
1610 baseline_report: json!({"name": "support@v3", "summary": {"run_pass_rate": 0.5}}),
1611 candidate_report: json!({"name": "support@v3", "summary": {"run_pass_rate": 0.9}}),
1612 verdict: EvaluationVerdict {
1613 regressed: false,
1614 target_metric: "run_pass_rate".into(),
1615 baseline: Some(0.5),
1616 candidate: Some(0.5 + delta),
1617 delta: Some(delta),
1618 },
1619 thresholds: EvaluationThresholds::default(),
1620 evaluated_by: distiller(),
1621 evaluated_at: ts(3_000),
1622 }
1623 }
1624
1625 #[test]
1626 fn candidate_id_is_a_content_address() {
1627 let a = memory_set_candidate(json!({"tone": "warm"}));
1628 let b = memory_set_candidate(json!({"tone": "warm"}));
1629 let c = memory_set_candidate(json!({"tone": "cold"}));
1630 // Same change converges — even across distillers and instants…
1631 assert_eq!(a.candidate_id, b.candidate_id);
1632 let d = Candidate::new(
1633 a.content.clone(),
1634 ProvenanceAuthor::System,
1635 EvidenceSpan::default(),
1636 ts(9_999),
1637 )
1638 .unwrap();
1639 assert_eq!(a.candidate_id, d.candidate_id);
1640 // …changed content is a new id.
1641 assert_ne!(a.candidate_id, c.candidate_id);
1642 assert_eq!(a.candidate_id.as_str().len(), 64);
1643 }
1644
1645 #[test]
1646 fn tampered_candidate_fails_its_own_address() {
1647 let mut candidate = memory_set_candidate(json!({"tone": "warm"}));
1648 candidate.verify_address().unwrap();
1649 candidate.candidate_id = CandidateId("f".repeat(64));
1650 assert!(matches!(
1651 candidate.verify_address(),
1652 Err(LearnError::AddressMismatch { .. })
1653 ));
1654 }
1655
1656 #[test]
1657 fn surfaces_are_the_documented_keys() {
1658 let memory = memory_set_candidate(json!({}));
1659 assert_eq!(memory.surface().as_str(), "memory:agent:support-1");
1660 let prompt = Candidate::new(
1661 CandidateContent::Prompt {
1662 name: "system".into(),
1663 prompt: "You are careful.".into(),
1664 },
1665 distiller(),
1666 EvidenceSpan::default(),
1667 ts(2_000),
1668 )
1669 .unwrap();
1670 assert_eq!(prompt.surface().as_str(), "prompt:system");
1671 let policy = Candidate::new(
1672 CandidateContent::Policy {
1673 family: DecisionFamily::Retry,
1674 parameters: json!({"max_attempts": 4}),
1675 },
1676 distiller(),
1677 EvidenceSpan::default(),
1678 ts(2_000),
1679 )
1680 .unwrap();
1681 assert_eq!(policy.surface().as_str(), "policy:retry");
1682 let tool = Candidate::new(
1683 CandidateContent::ToolPermission {
1684 tool: "shell".into(),
1685 direction: GrantDirection::Narrow,
1686 },
1687 distiller(),
1688 EvidenceSpan::default(),
1689 ts(2_000),
1690 )
1691 .unwrap();
1692 assert_eq!(tool.surface().as_str(), "tool:shell");
1693 }
1694
1695 #[test]
1696 fn lifecycle_refuses_illegal_transitions() {
1697 let candidate = memory_set_candidate(json!({}));
1698 let mut record = CandidateRecord::new(candidate.clone());
1699 // Promote before evaluate: refused, typed.
1700 let receipt = PromotionReceipt {
1701 candidate_id: candidate.candidate_id.clone(),
1702 surface: candidate.surface(),
1703 previous: None,
1704 decision: PromotionDecision {
1705 authority: PromotionAuthority::Envelope {
1706 envelope_version: "r0.8-default".into(),
1707 },
1708 canary: None,
1709 },
1710 promoted_at: ts(4_000),
1711 };
1712 assert!(matches!(
1713 record.apply_promotion(receipt.clone()),
1714 Err(LearnError::InvalidTransition {
1715 from: CandidateStatus::Created,
1716 action: "promote",
1717 })
1718 ));
1719 // Evaluate, then promote, then refuse re-evaluation and allow rollback.
1720 record
1721 .apply_evaluation(clean_evaluation(&candidate, 0.4))
1722 .unwrap();
1723 record.apply_promotion(receipt).unwrap();
1724 assert!(matches!(
1725 record.apply_evaluation(clean_evaluation(&candidate, 0.5)),
1726 Err(LearnError::InvalidTransition {
1727 from: CandidateStatus::Promoted,
1728 action: "evaluate",
1729 })
1730 ));
1731 record
1732 .apply_rollback(RollbackReceipt {
1733 surface: candidate.surface(),
1734 from: candidate.candidate_id.clone(),
1735 to: None,
1736 cause: "operator: drift on run-9".into(),
1737 rolled_back_at: ts(5_000),
1738 })
1739 .unwrap();
1740 assert_eq!(record.status, CandidateStatus::RolledBack);
1741 }
1742
1743 #[test]
1744 fn gate_admits_in_envelope_and_refuses_out_of_it() {
1745 let envelope = PromotionEnvelope::r08_default();
1746 let candidate = memory_set_candidate(json!({"tone": "warm"}));
1747 let evaluation = clean_evaluation(&candidate, 0.4);
1748 // In-envelope: memory_set at agent scope, clean verdict → the
1749 // envelope version is the standing approval.
1750 let decision = admit_promotion(&envelope, &candidate, Some(&evaluation), None).unwrap();
1751 assert_eq!(
1752 decision.authority,
1753 PromotionAuthority::Envelope {
1754 envelope_version: "r0.8-default".into()
1755 }
1756 );
1757 // Out-of-envelope: prompt candidates always need a token in R0.8.
1758 let prompt = Candidate::new(
1759 CandidateContent::Prompt {
1760 name: "system".into(),
1761 prompt: "You are careful.".into(),
1762 },
1763 distiller(),
1764 EvidenceSpan::default(),
1765 ts(2_000),
1766 )
1767 .unwrap();
1768 let prompt_eval = clean_evaluation(&prompt, 0.4);
1769 let refused = admit_promotion(&envelope, &prompt, Some(&prompt_eval), None).unwrap_err();
1770 let effect_id = promotion_effect_id(&prompt);
1771 assert_eq!(
1772 refused,
1773 LearnError::Refused(PromotionRefusal::RequiresApproval {
1774 effect_id: effect_id.clone()
1775 })
1776 );
1777 // A token for another candidate's promotion does not transfer…
1778 let wrong = ApprovalToken::approve(promotion_effect_id(&candidate), "ops:amjad");
1779 assert!(matches!(
1780 admit_promotion(&envelope, &prompt, Some(&prompt_eval), Some(&wrong)),
1781 Err(LearnError::Refused(
1782 PromotionRefusal::ApprovalMismatch { .. }
1783 ))
1784 ));
1785 // …the correctly scoped token admits, with attribution.
1786 let token = ApprovalToken::approve(effect_id, "ops:amjad");
1787 let decision =
1788 admit_promotion(&envelope, &prompt, Some(&prompt_eval), Some(&token)).unwrap();
1789 assert_eq!(
1790 decision.authority,
1791 PromotionAuthority::Approval {
1792 approved_by: "ops:amjad".into()
1793 }
1794 );
1795 }
1796
1797 #[test]
1798 fn gate_enforces_the_evidence_bar() {
1799 let envelope = PromotionEnvelope::r08_default();
1800 let candidate = memory_set_candidate(json!({}));
1801 // Parity is not improvement.
1802 let parity = clean_evaluation(&candidate, 0.0);
1803 assert_eq!(
1804 admit_promotion(&envelope, &candidate, Some(&parity), None).unwrap_err(),
1805 LearnError::Refused(PromotionRefusal::InsufficientImprovement {
1806 delta: Some(0.0),
1807 required: 0.0,
1808 })
1809 );
1810 // Regression refuses even with improvement on the target metric.
1811 let mut regressed = clean_evaluation(&candidate, 0.4);
1812 regressed.verdict.regressed = true;
1813 assert!(matches!(
1814 admit_promotion(&envelope, &candidate, Some(®ressed), None),
1815 Err(LearnError::Refused(
1816 PromotionRefusal::EvaluationRegressed { .. }
1817 ))
1818 ));
1819 // Divergent replay refuses.
1820 let mut diverged = clean_evaluation(&candidate, 0.4);
1821 diverged.replay.divergences = vec![ReplayDivergence {
1822 fixture_id: "run-1".into(),
1823 detail: "seq 4: request hash mismatch".into(),
1824 }];
1825 assert!(matches!(
1826 admit_promotion(&envelope, &candidate, Some(&diverged), None),
1827 Err(LearnError::Refused(PromotionRefusal::ReplayDiverged { .. }))
1828 ));
1829 // A wider scope than the R0.8 default refuses.
1830 let tenant_scoped = Candidate::new(
1831 CandidateContent::MemorySet {
1832 scope: ScopeAddress::new(MemoryScope::Tenant, "default"),
1833 adds: vec![],
1834 supersedes: vec![],
1835 },
1836 distiller(),
1837 EvidenceSpan::default(),
1838 ts(2_000),
1839 )
1840 .unwrap();
1841 let evaluation = clean_evaluation(&tenant_scoped, 0.4);
1842 assert!(matches!(
1843 admit_promotion(&envelope, &tenant_scoped, Some(&evaluation), None),
1844 Err(LearnError::Refused(
1845 PromotionRefusal::ScopeNotAutoPromotable {
1846 scope: MemoryScope::Tenant
1847 }
1848 ))
1849 ));
1850 // No evaluation at all refuses, even for an in-envelope kind.
1851 assert!(matches!(
1852 admit_promotion(&envelope, &candidate, None, None),
1853 Err(LearnError::Refused(PromotionRefusal::NotEvaluated { .. }))
1854 ));
1855 }
1856
1857 #[test]
1858 fn canary_draw_is_deterministic_uniform_and_scoped() {
1859 let candidate = memory_set_candidate(json!({}));
1860 let surface = candidate.surface();
1861 let binding = CanaryBinding {
1862 candidate_id: candidate.candidate_id.clone(),
1863 fraction: 0.25,
1864 };
1865 // Deterministic per (surface, candidate, run).
1866 assert_eq!(
1867 canary_admits(&binding, &surface, "run-7"),
1868 canary_admits(&binding, &surface, "run-7")
1869 );
1870 // Full fraction admits everything.
1871 let full = CanaryBinding {
1872 candidate_id: candidate.candidate_id.clone(),
1873 fraction: 1.0,
1874 };
1875 for run in 0..32 {
1876 assert!(canary_admits(&full, &surface, &format!("run-{run}")));
1877 }
1878 // A quarter fraction admits roughly a quarter of traffic (loose
1879 // bounds: the draw is uniform over the digest space).
1880 let admitted = (0..1_000)
1881 .filter(|run| canary_admits(&binding, &surface, &format!("run-{run}")))
1882 .count();
1883 assert!(
1884 (150..=350).contains(&admitted),
1885 "fraction 0.25 admitted {admitted}/1000 runs"
1886 );
1887 }
1888
1889 #[test]
1890 fn pointer_moves_on_promotion_and_reponts_on_rollback() {
1891 let a = memory_set_candidate(json!({"v": "a"}));
1892 let b = memory_set_candidate(json!({"v": "b"}));
1893 let pointer = VersionPointer::new(a.surface());
1894 assert_eq!(pointer.active, None);
1895
1896 let promote_a = PromotionReceipt {
1897 candidate_id: a.candidate_id.clone(),
1898 surface: a.surface(),
1899 previous: None,
1900 decision: PromotionDecision {
1901 authority: PromotionAuthority::Envelope {
1902 envelope_version: "r0.8-default".into(),
1903 },
1904 canary: None,
1905 },
1906 promoted_at: ts(4_000),
1907 };
1908 let pointer = pointer.promoted(&promote_a);
1909 assert_eq!(pointer.active, Some(a.candidate_id.clone()));
1910
1911 let promote_b = PromotionReceipt {
1912 candidate_id: b.candidate_id.clone(),
1913 surface: a.surface(),
1914 previous: Some(a.candidate_id.clone()),
1915 decision: promote_a.decision.clone(),
1916 promoted_at: ts(5_000),
1917 };
1918 let pointer = pointer.promoted(&promote_b);
1919 assert_eq!(pointer.active, Some(b.candidate_id.clone()));
1920
1921 // Rollback re-points to the previous candidate — byte-exact,
1922 // because the candidate id IS the content.
1923 let pointer = pointer.rolled_back(&RollbackReceipt {
1924 surface: a.surface(),
1925 from: b.candidate_id.clone(),
1926 to: promote_b.previous.clone(),
1927 cause: "drift".into(),
1928 rolled_back_at: ts(6_000),
1929 });
1930 assert_eq!(pointer.active, Some(a.candidate_id.clone()));
1931 }
1932
1933 #[tokio::test]
1934 async fn overlay_applies_the_candidate_as_a_read_lens() {
1935 let base = Arc::new(InMemoryMemoryStore::new());
1936 let existing = memory_record(json!({"tone": "flat"}));
1937 base.put(&existing).await.unwrap();
1938
1939 let mut added = memory_record(json!({"tone": "warm"}));
1940 added.supersedes = Some(existing.memory_id.clone());
1941 let candidate = Candidate::new(
1942 CandidateContent::MemorySet {
1943 scope: ScopeAddress::new(MemoryScope::Agent, "support-1"),
1944 adds: vec![added.clone()],
1945 supersedes: Vec::new(),
1946 },
1947 distiller(),
1948 EvidenceSpan::default(),
1949 ts(2_000),
1950 )
1951 .unwrap();
1952 let overlay = CandidateOverlay::new(base.clone(), &candidate).unwrap();
1953 // The add answers…
1954 assert_eq!(overlay.get(&added.memory_id).await.unwrap(), Some(added));
1955 // …the base record still fetches by id…
1956 assert_eq!(
1957 overlay.get(&existing.memory_id).await.unwrap(),
1958 Some(existing.clone())
1959 );
1960 // …but drops out of default retrieval via the add's supersedes
1961 // field (core's matcher, over the merged universe)…
1962 let listed = overlay
1963 .query(&MemoryQuery::default(), Utc::now())
1964 .await
1965 .unwrap();
1966 assert_eq!(listed.len(), 1);
1967 // …and writes through the lens fail.
1968 assert!(overlay.put(&existing).await.is_err());
1969 }
1970}