Skip to main content

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(&regressed), 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}