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`, extended additively in R0.11 (wave 1) with
23//!   `tool_contract` / `model_settings` / `memory_configuration` /
24//!   `middleware_composition` — the registry families the Extension Plane
25//!   design's artifact table names as new kinds.
26//! - [`CandidateEvaluation`] — the journaled evaluation payload: the
27//!   replay divergence summary, the experiment report pair, the dataset
28//!   version, and the comparison verdict. The evaluator itself is a seam
29//!   ([`CandidateEvaluator`]), not runtime code — the same boundary open
30//!   question 2 draws for distillers, forced by the workspace's dependency
31//!   direction: `rusty-eval` links the runtime, never the reverse, so the
32//!   runtime owns the journaled *shape* of the evaluation and the
33//!   application owns producing it through `rusty-eval`'s
34//!   `ExperimentRunner` + `compare()`. [`EvaluationVerdict`] and
35//!   [`EvaluationThresholds`] are the deliberate mirrors of `compare()`'s
36//!   output and `CompareThresholds` — one serde-pinned record reference,
37//!   the same way `rusty-eval` already meets the runtime at the `Journal`.
38//! - [`PromotionEnvelope`] — the declared, per-deployment standing
39//!   approval: per candidate kind, what may auto-promote (the evidence
40//!   thresholds), what requires a human approval, and what promotes into
41//!   a canary. The gate is [`admit_promotion`], a pure function; refusal
42//!   is a typed error ([`PromotionRefusal`]), never a silent no-op.
43//!   Out-of-envelope promotion requires an
44//!   [`crate::effects::ApprovalToken`] scoped to
45//!   [`promotion_effect_id`] — derived over the candidate's content hash
46//!   and target scope, so an approval for one candidate is
47//!   non-transferable to another. This composes the effect kernel rather
48//!   than inventing an approval parallel to it.
49//! - [`VersionPointer`] — the active version per surface (prompt name,
50//!   policy scope, memory scope, tool grant) as an immutable pointer to a
51//!   [`CandidateId`]. Every promotion is a pointer move; rollback
52//!   re-points to the previous candidate and is byte-exact because
53//!   candidates are content-addressed and immutable — the restored
54//!   version is the one that previously served, not a reconstruction.
55//!
56//! Every lifecycle transition (created → evaluated → promoted → rolled
57//! back) journals through four additive [`RunEventKind`](crate::record::RunEventKind) variants —
58//! `CandidateCreated` / `CandidateEvaluated` / `CandidatePromoted` /
59//! `CandidateRolledBack` — the same evolution rule R0.6's `EffectReceipt`
60//! and R0.7's agent variants followed; old journals keep deserializing.
61//! Refused transitions are errors ([`LearnError`]), not silent no-ops.
62//!
63//! Golden-file tests under `tests/golden/` pin every wire shape in this
64//! module; any accidental contract drift fails CI.
65
66use std::collections::HashSet;
67use std::sync::Arc;
68
69use async_trait::async_trait;
70use chrono::{DateTime, Utc};
71use serde::{Deserialize, Serialize};
72use serde_json::Value;
73use sha2::{Digest, Sha256};
74use thiserror::Error;
75
76use crate::effects::{derive_effect_id, ApprovalToken, EffectId};
77use crate::error::{Result, RustyError};
78use crate::journal::JournalSnapshot;
79use crate::memory::{
80    apply_query, ContextBudget, MemoryQuery, MemoryRecord, MemoryScope, MemoryStore,
81    ProvenanceAuthor, ScopeAddress,
82};
83use crate::record::{sha256_hex, DecisionFamily, RunManifest};
84
85fn invalid(message: impl Into<String>) -> RustyError {
86    // Candidate construction and application are state updates to the
87    // governed learning plane; contract validation failures reuse the
88    // invalid-update class rather than growing the error taxonomy for one
89    // module (the memory module's own convention).
90    RustyError::InvalidUpdate(message.into())
91}
92
93// --------------------------------------------------------------------- //
94// The candidate contract
95// --------------------------------------------------------------------- //
96
97/// A content-addressed candidate identity: lowercase hex SHA-256 over the
98/// candidate's canonical content ([`derive_candidate_id`]).
99///
100/// Transparent newtype so the type system — not convention — keeps
101/// candidate ids distinct from memory addresses, effect ids, and other
102/// digest strings (the [`PolicyVersion`] / [`EffectId`] precedent).
103#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
104#[serde(transparent)]
105pub struct CandidateId(String);
106
107impl CandidateId {
108    /// The hex digest.
109    pub fn as_str(&self) -> &str {
110        &self.0
111    }
112}
113
114impl std::fmt::Display for CandidateId {
115    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
116        f.write_str(&self.0)
117    }
118}
119
120impl From<String> for CandidateId {
121    /// Wrap a digest the caller already trusts — rehydration from storage,
122    /// a rollback receipt's `previous`. Minting ids from content is
123    /// [`derive_candidate_id`]'s job alone; nothing here re-verifies.
124    fn from(digest: String) -> Self {
125        Self(digest)
126    }
127}
128
129/// What a candidate would change. Closed enum — the gate, the pointer,
130/// and the evaluator match exhaustively on it.
131///
132/// R0.11 (Extension Plane, wave 1) extends the enum additively with the
133/// registry families the design's artifact table names as new kinds:
134/// tool contracts, model settings, memory configurations, and middleware
135/// compositions. The evolution rule is the one R0.10 applied when it
136/// weighed a `Speculation` family and deferred it: new variants append,
137/// golden files pin every wire shape, and old records keep deserializing.
138#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
139#[serde(rename_all = "snake_case")]
140pub enum CandidateKind {
141    /// New prompt text for one named prompt.
142    Prompt,
143    /// Executor policy parameters for one decision family.
144    Policy,
145    /// A set of memory records (adds and supersessions).
146    MemorySet,
147    /// A narrowed or widened tool grant.
148    ToolPermission,
149    /// The JSON schema a tool's manifest pin digests (R0.11).
150    ToolContract,
151    /// A model id plus its parameters (R0.11).
152    ModelSettings,
153    /// Memory retrieval/assembly settings — distinct from
154    /// [`CandidateKind::MemorySet`], which carries *records*; this kind
155    /// carries the configuration that shapes what reads return (R0.11).
156    MemoryConfiguration,
157    /// An ordered middleware layer list plus per-layer configuration
158    /// (R0.11).
159    MiddlewareComposition,
160}
161
162impl CandidateKind {
163    /// The wire name (`prompt` / `policy` / `memory_set` /
164    /// `tool_permission` / `tool_contract` / `model_settings` /
165    /// `memory_configuration` / `middleware_composition`).
166    pub fn as_str(&self) -> &'static str {
167        match self {
168            CandidateKind::Prompt => "prompt",
169            CandidateKind::Policy => "policy",
170            CandidateKind::MemorySet => "memory_set",
171            CandidateKind::ToolPermission => "tool_permission",
172            CandidateKind::ToolContract => "tool_contract",
173            CandidateKind::ModelSettings => "model_settings",
174            CandidateKind::MemoryConfiguration => "memory_configuration",
175            CandidateKind::MiddlewareComposition => "middleware_composition",
176        }
177    }
178}
179
180impl std::fmt::Display for CandidateKind {
181    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
182        f.write_str(self.as_str())
183    }
184}
185
186/// The direction of a [`CandidateContent::ToolPermission`] change.
187/// Closed enum: the direction is the R0.8 contract — grant mechanics
188/// (which capabilities a narrowed grant drops, how a widened one is
189/// bounded) are R0.9's capsule-manifest work, and this release gates
190/// every tool-permission candidate behind a human approval regardless.
191#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
192#[serde(rename_all = "snake_case")]
193pub enum GrantDirection {
194    /// The grant shrinks (a capability is withdrawn).
195    Narrow,
196    /// The grant grows (a capability is added).
197    Widen,
198}
199
200/// The change a candidate declares, per [`CandidateKind`]. Serialized with
201/// internal tagging (`{"kind": "memory_set", …}`): the kind is part of
202/// the content address — a prompt text and a policy parameter set that
203/// happened to serialize alike must never converge.
204#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
205#[serde(tag = "kind", rename_all = "snake_case")]
206pub enum CandidateContent {
207    /// New prompt text. The text's digest — `sha256_hex` over its UTF-8
208    /// bytes — is exactly the pin [`RunManifest::pin_prompt`] records, so
209    /// the candidate and the run manifest speak one content address.
210    Prompt {
211        /// The prompt's name (the manifest pin's key).
212        name: String,
213        /// The proposed prompt text.
214        prompt: String,
215    },
216    /// Executor policy parameters for one
217    /// [`crate::record::DecisionFamily`] — backoff caps, timeout bounds,
218    /// concurrency limits. The closed legal-action sets stay closed: a
219    /// learned policy chooses among declared actions, never free-form
220    /// outputs.
221    Policy {
222        /// The decision family the parameters govern.
223        family: DecisionFamily,
224        /// The parameter set (schema is the policy registry's, wave 4).
225        parameters: Value,
226    },
227    /// A set of memory records at one scope: adds and supersessions.
228    /// Carrying full [`MemoryRecord`]s — not ids — is what lets the set
229    /// carry wave 2's attributed correction candidates: the records'
230    /// provenance (and therefore their own content addresses) is inside
231    /// this candidate's address.
232    MemorySet {
233        /// The scope the set applies at.
234        scope: ScopeAddress,
235        /// The records the set adds (already content-addressed, already
236        /// immutable — a record in two sets is the same record).
237        adds: Vec<MemoryRecord>,
238        /// Bare memory content addresses the set supersedes beyond the
239        /// adds' own `supersedes` fields.
240        #[serde(default, skip_serializing_if = "Vec::is_empty")]
241        supersedes: Vec<String>,
242    },
243    /// A narrowed or widened tool grant.
244    ToolPermission {
245        /// The tool whose grant changes.
246        tool: String,
247        /// The direction of the change (see [`GrantDirection`]).
248        direction: GrantDirection,
249    },
250    /// The JSON schema a tool's pin digests (R0.11). The digest —
251    /// canonical-JSON SHA-256 — is exactly what
252    /// [`RunManifest::pin_tool_schema`] records, so the candidate and the
253    /// manifest speak one content address, the
254    /// [`CandidateContent::Prompt`] precedent applied to tool schemas.
255    ToolContract {
256        /// The tool whose contract changes (the manifest pin's key).
257        tool: String,
258        /// The parameters schema the tool declares.
259        schema: Value,
260    },
261    /// A model id plus its parameters (R0.11). The pair is what
262    /// [`RunManifest::pin_model`] pins: the provider-precise model id
263    /// verbatim, the parameters as a canonical-JSON digest.
264    ModelSettings {
265        /// The settings' name (the registry artifact's key part).
266        name: String,
267        /// The provider-precise model identifier (an alias is not a pin).
268        model: String,
269        /// The parameter set (temperature, seed, token limits, ...).
270        parameters: Value,
271    },
272    /// Memory retrieval/assembly settings (R0.11): the budget and default
273    /// filters that shape what a run's memory reads return, plus the
274    /// record-schema version the settings assume (the
275    /// `manifest.memory_schema` pin). Deliberately a new kind rather than
276    /// a [`CandidateContent::MemorySet`] reuse: a memory set carries
277    /// *records* at a scope; this carries the configuration reads run
278    /// under. Conflating the two would fake coverage.
279    MemoryConfiguration {
280        /// The configuration's name (the registry artifact's key part).
281        name: String,
282        /// The default assembly budget reads run under.
283        budget: ContextBudget,
284        /// The default filters reads start from (a run's own query
285        /// narrows further; it never widens past the configuration).
286        default_filters: MemoryQuery,
287        /// The memory record-schema version the settings assume.
288        schema_version: String,
289    },
290    /// An ordered middleware layer list plus per-layer configuration
291    /// (R0.11): interception policy versioned like everything else. The
292    /// layers are code — the registry versions their composition and
293    /// configuration, not their behavior; a layer's logic change is a
294    /// deploy, covered by the checkpoint header's `graph_hash` story.
295    MiddlewareComposition {
296        /// The composition's name (the registry artifact's key part).
297        name: String,
298        /// The layers in declared order — before-hooks run in this order,
299        /// after-hooks in reverse (the chain's onion semantics, governed
300        /// here, untouched there).
301        layers: Vec<MiddlewareLayerConfig>,
302    },
303}
304
305/// One layer in a [`CandidateContent::MiddlewareComposition`]: the layer's
306/// registered name plus its configuration. A `ToolCallBlocklist`'s policy
307/// is configuration; the layer's code is not.
308#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
309pub struct MiddlewareLayerConfig {
310    /// The layer's registered name (the
311    /// [`crate::middleware::MiddlewareChain::names`] vocabulary).
312    pub layer: String,
313
314    /// The layer's configuration, when it declares one — absent from the
315    /// wire when unset, so a configuration-free layer (a request logger)
316    /// carries no placeholder.
317    #[serde(default, skip_serializing_if = "Option::is_none")]
318    pub config: Option<Value>,
319}
320
321/// The content address of a candidate: `sha256` over the canonical
322/// serialization of its content — the one hashing primitive shared with
323/// artifact references and journal heads, over the canonical `serde_json`
324/// serialization [`crate::record::PayloadRef::content_hash`] also relies
325/// on (object keys sort deterministically).
326pub fn derive_candidate_id(content: &CandidateContent) -> Result<CandidateId> {
327    Ok(CandidateId(sha256_hex(&serde_json::to_vec(content)?)))
328}
329
330/// The evidence span a distiller read to produce a candidate — journaled
331/// with creation, because a candidate that cannot name its observations
332/// cannot be audited. Every field is optional and absent from the wire
333/// when empty: a hand-authored candidate may carry no span at all, and
334/// sparse evidence must not change the shape for dense readers.
335#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
336pub struct EvidenceSpan {
337    /// The recorded runs whose journals the distiller read. "Completed"
338    /// is load-bearing (the design's observe stage): learning reads
339    /// terminal evidence, never in-flight state.
340    #[serde(default, skip_serializing_if = "Vec::is_empty")]
341    pub run_ids: Vec<String>,
342
343    /// The corrections (R0.8 wave 2) the candidate folds in — the
344    /// reference distiller's input.
345    #[serde(default, skip_serializing_if = "Vec::is_empty")]
346    pub correction_ids: Vec<String>,
347
348    /// The memory records the distiller read (e.g. the attributed
349    /// candidates a `memory_set` carries).
350    #[serde(default, skip_serializing_if = "Vec::is_empty")]
351    pub memory_ids: Vec<String>,
352}
353
354impl EvidenceSpan {
355    /// `true` when no span is carried (the sparse wire shape).
356    pub fn is_empty(&self) -> bool {
357        self.run_ids.is_empty() && self.correction_ids.is_empty() && self.memory_ids.is_empty()
358    }
359}
360
361/// A proposed change: immutable, versioned, content-addressed.
362///
363/// The address covers the **content** — the change itself — and nothing
364/// else: two distillations of the same change converge on one id even
365/// when different distillers read different evidence to reach it (the
366/// design's identity-is-integrity rule). Attribution is not identity, so
367/// the distiller, the evidence span, and the learning instant travel
368/// beside the address rather than inside it — the inverse of
369/// [`MemoryRecord`]'s provenance-in-identity rule, deliberate: a memory
370/// record answers "who claims this," a candidate answers "what would
371/// change."
372///
373/// Immutable by construction: a changed candidate is a new id, and there
374/// is no in-place update anywhere in the pipeline.
375#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
376pub struct Candidate {
377    /// The content address ([`derive_candidate_id`]).
378    pub candidate_id: CandidateId,
379
380    /// The change, per kind.
381    pub content: CandidateContent,
382
383    /// The distiller's identity. Mandatory — journaled with creation
384    /// (`CandidateCreated`), because a candidate that cannot name its
385    /// distiller is indistinguishable from a config edit.
386    pub distilled_by: ProvenanceAuthor,
387
388    /// The evidence span the distiller read. Absent from the wire when
389    /// empty.
390    #[serde(default, skip_serializing_if = "EvidenceSpan::is_empty")]
391    pub evidence: EvidenceSpan,
392
393    /// When the distiller minted the candidate.
394    pub created_at: DateTime<Utc>,
395}
396
397impl Candidate {
398    /// Build a candidate, deriving its content address from `content`.
399    pub fn new(
400        content: CandidateContent,
401        distilled_by: ProvenanceAuthor,
402        evidence: EvidenceSpan,
403        created_at: DateTime<Utc>,
404    ) -> Result<Self> {
405        let candidate_id = derive_candidate_id(&content)?;
406        Ok(Self {
407            candidate_id,
408            content,
409            distilled_by,
410            evidence,
411            created_at,
412        })
413    }
414
415    /// The candidate's kind.
416    pub fn kind(&self) -> CandidateKind {
417        match &self.content {
418            CandidateContent::Prompt { .. } => CandidateKind::Prompt,
419            CandidateContent::Policy { .. } => CandidateKind::Policy,
420            CandidateContent::MemorySet { .. } => CandidateKind::MemorySet,
421            CandidateContent::ToolPermission { .. } => CandidateKind::ToolPermission,
422            CandidateContent::ToolContract { .. } => CandidateKind::ToolContract,
423            CandidateContent::ModelSettings { .. } => CandidateKind::ModelSettings,
424            CandidateContent::MemoryConfiguration { .. } => CandidateKind::MemoryConfiguration,
425            CandidateContent::MiddlewareComposition { .. } => CandidateKind::MiddlewareComposition,
426        }
427    }
428
429    /// The production surface this candidate would change — the pointer
430    /// key: `prompt:{name}` / `policy:{family}` / `memory:{scope}` /
431    /// `tool:{tool}` / `tool_contract:{tool}` / `model_settings:{name}` /
432    /// `memory_config:{name}` / `middleware:{name}`. One surface admits
433    /// one active version, which is what makes promotion a pointer move
434    /// and rollback a re-pointing.
435    pub fn surface(&self) -> SurfaceKey {
436        match &self.content {
437            CandidateContent::Prompt { name, .. } => surface_for_kind(CandidateKind::Prompt, name),
438            CandidateContent::Policy { family, .. } => {
439                let family = serde_json::to_value(family)
440                    .ok()
441                    .and_then(|v| v.as_str().map(str::to_owned))
442                    .unwrap_or_else(|| format!("{family:?}").to_lowercase());
443                surface_for_kind(CandidateKind::Policy, &family)
444            }
445            CandidateContent::MemorySet { scope, .. } => {
446                surface_for_kind(CandidateKind::MemorySet, &scope.as_address())
447            }
448            CandidateContent::ToolPermission { tool, .. } => {
449                surface_for_kind(CandidateKind::ToolPermission, tool)
450            }
451            CandidateContent::ToolContract { tool, .. } => {
452                surface_for_kind(CandidateKind::ToolContract, tool)
453            }
454            CandidateContent::ModelSettings { name, .. } => {
455                surface_for_kind(CandidateKind::ModelSettings, name)
456            }
457            CandidateContent::MemoryConfiguration { name, .. } => {
458                surface_for_kind(CandidateKind::MemoryConfiguration, name)
459            }
460            CandidateContent::MiddlewareComposition { name, .. } => {
461                surface_for_kind(CandidateKind::MiddlewareComposition, name)
462            }
463        }
464    }
465
466    /// Re-derive the content address and compare: `Ok` when the candidate
467    /// is the one its id names. Identity is integrity — the gate runs
468    /// this before any promotion, so a tampered candidate fails closed at
469    /// the boundary, not after a pointer moved.
470    pub fn verify_address(&self) -> std::result::Result<(), LearnError> {
471        let derived = derive_candidate_id(&self.content)
472            .map_err(|e| LearnError::UnaddressableContent(e.to_string()))?;
473        if derived != self.candidate_id {
474            return Err(LearnError::AddressMismatch {
475                claimed: self.candidate_id.clone(),
476                derived,
477            });
478        }
479        Ok(())
480    }
481
482    /// Apply a `prompt` candidate to a manifest: substitute the named
483    /// prompt's pin with the candidate's — the same digest
484    /// [`RunManifest::pin_prompt`] records, so the evaluation's manifest
485    /// speaks the production surface's content address. Every other kind
486    /// fails: a candidate applies only to the surface its kind declares.
487    pub fn apply_to_manifest(&self, manifest: &mut RunManifest) -> Result<()> {
488        let CandidateContent::Prompt { name, prompt } = &self.content else {
489            return Err(invalid(format!(
490                "only a `prompt` candidate applies to a run manifest; `{}` candidates apply \
491                 to their own surfaces",
492                self.kind_str()
493            )));
494        };
495        manifest
496            .prompts
497            .insert(name.clone(), sha256_hex(prompt.as_bytes()));
498        Ok(())
499    }
500
501    fn kind_str(&self) -> &'static str {
502        self.kind().as_str()
503    }
504}
505
506/// The surface key for one kind's named surface: `prompt:{name}` /
507/// `policy:{family}` / `memory:{scope-address}` / `tool:{tool}` /
508/// `tool_contract:{tool}` / `model_settings:{name}` /
509/// `memory_config:{name}` / `middleware:{name}`.
510///
511/// [`Candidate::surface`] builds its key through this function, and the
512/// configuration registry (`crate::registry`) keys artifacts by the same
513/// rule — one surface admits one artifact, so a candidate can only ever
514/// join the artifact its own surface names.
515pub fn surface_for_kind(kind: CandidateKind, name: &str) -> SurfaceKey {
516    let prefix = match kind {
517        CandidateKind::Prompt => "prompt",
518        CandidateKind::Policy => "policy",
519        CandidateKind::MemorySet => "memory",
520        CandidateKind::ToolPermission => "tool",
521        CandidateKind::ToolContract => "tool_contract",
522        CandidateKind::ModelSettings => "model_settings",
523        CandidateKind::MemoryConfiguration => "memory_config",
524        CandidateKind::MiddlewareComposition => "middleware",
525    };
526    SurfaceKey::new(format!("{prefix}:{name}"))
527}
528
529/// A candidate's production surface: the pointer key. Transparent newtype
530/// over the canonical `{kind}:{scope}` string ([`Candidate::surface`]).
531#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
532#[serde(transparent)]
533pub struct SurfaceKey(String);
534
535impl SurfaceKey {
536    /// Wrap a surface string (built by [`Candidate::surface`]).
537    pub fn new(surface: impl Into<String>) -> Self {
538        Self(surface.into())
539    }
540
541    /// The surface string.
542    pub fn as_str(&self) -> &str {
543        &self.0
544    }
545}
546
547impl std::fmt::Display for SurfaceKey {
548    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
549        f.write_str(&self.0)
550    }
551}
552
553// --------------------------------------------------------------------- //
554// Environment tags on surfaces (R0.11 Extension Plane, wave 1)
555// --------------------------------------------------------------------- //
556
557/// The separator between a surface key and its environment tag
558/// (`prompt:system@prod`). One character, reserved: artifact names never
559/// carry it (the registry's naming rule), so the last separator in a key
560/// always introduces the tag.
561pub const SURFACE_TAG_SEPARATOR: char = '@';
562
563/// An environment tag on a promotion target: `dev` / `staging` / `prod`
564/// by convention, deployment-declared rather than enumerated — R0.11's
565/// tags are labels on promotion targets, not deployments (R0.12 builds
566/// environments as a control plane). What a tag is *not*: not an isolated
567/// store, not a trust boundary. One deployment serves the prod surface
568/// and the staging surface from one registry, with envelope strictness
569/// per tag.
570///
571/// The tag rides inside the surface key (`prompt:system@prod`), so the
572/// pointer store, hash-named files, transactional moves, and canary slots
573/// all work unchanged — the design's open question 1, settled as leaned.
574#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize)]
575#[serde(transparent)]
576pub struct EnvironmentTag(String);
577
578impl EnvironmentTag {
579    /// The longest a tag may be. Tags live inside pointer keys, receipts,
580    /// and journaled payloads; a bound keeps a configuration typo from
581    /// minting an unbounded key.
582    pub const MAX_LEN: usize = 64;
583
584    /// Mint a tag. Refused: empty, over-long, carrying whitespace or
585    /// control characters, or carrying [`SURFACE_TAG_SEPARATOR`] or `/`
586    /// (the tenant id-prefix separator) — the characters that would make
587    /// the tagged key ambiguous downstream. Validation failures reuse the
588    /// invalid-update class, the module's convention for contract
589    /// violations at construction time.
590    pub fn new(tag: impl Into<String>) -> Result<Self> {
591        let tag = tag.into();
592        let refuse = |reason: &str| invalid(format!("invalid environment tag {tag:?}: {reason}"));
593        if tag.is_empty() {
594            return Err(refuse(
595                "empty — an absent tag is the untagged surface, spelled `None`",
596            ));
597        }
598        if tag.len() > Self::MAX_LEN {
599            return Err(refuse("over 64 bytes"));
600        }
601        if tag
602            .chars()
603            .any(|c| c.is_whitespace() || c.is_control() || c == SURFACE_TAG_SEPARATOR || c == '/')
604        {
605            return Err(refuse(
606                "carries whitespace, a control character, `@`, or `/` — the first two have no \
607                 business in a key, the last two are the tag and tenant separators",
608            ));
609        }
610        Ok(Self(tag))
611    }
612
613    /// The tag string.
614    pub fn as_str(&self) -> &str {
615        &self.0
616    }
617}
618
619impl std::fmt::Display for EnvironmentTag {
620    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
621        f.write_str(&self.0)
622    }
623}
624
625impl<'de> Deserialize<'de> for EnvironmentTag {
626    /// Validated at deserialization (the correction-author precedent): a
627    /// malformed tag in a request payload fails the parse, so no code path
628    /// downstream ever holds an unvalidated one.
629    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
630    where
631        D: serde::Deserializer<'de>,
632    {
633        let raw = String::deserialize(deserializer)?;
634        EnvironmentTag::new(raw).map_err(serde::de::Error::custom)
635    }
636}
637
638impl SurfaceKey {
639    /// The tagged surface for an environment (`prompt:system` at `prod` →
640    /// `prompt:system@prod`). Promotion composes the existing pointer
641    /// machinery: the tagged key is just another surface, so the pointer
642    /// store, canary slots, and byte-exact rollback work unchanged.
643    pub fn tagged(&self, tag: &EnvironmentTag) -> SurfaceKey {
644        SurfaceKey::new(format!(
645            "{}{}{}",
646            self.0,
647            SURFACE_TAG_SEPARATOR,
648            tag.as_str()
649        ))
650    }
651
652    /// Split a possibly tagged key into its base surface and tag, at the
653    /// last [`SURFACE_TAG_SEPARATOR`] (names never carry the separator, so
654    /// the last one always introduces the tag). The untagged key splits to
655    /// `(itself, None)`.
656    pub fn split_tag(&self) -> (SurfaceKey, Option<EnvironmentTag>) {
657        match self.0.rfind(SURFACE_TAG_SEPARATOR) {
658            Some(at) => {
659                let base = SurfaceKey::new(&self.0[..at]);
660                // The constructor cannot fail here: the tag came out of a
661                // key this module's own rules built (or a caller's raw
662                // string, which re-validates cleanly by construction of
663                // the split — any character that would be refused would
664                // have been refused when the key was tagged).
665                let tag = EnvironmentTag(self.0[at + 1..].to_owned());
666                (base, Some(tag))
667            }
668            None => (self.clone(), None),
669        }
670    }
671}
672
673// --------------------------------------------------------------------- //
674// Effect keys and the approval scope
675// --------------------------------------------------------------------- //
676
677/// The derived idempotency key of a candidate creation:
678/// `candidate:{candidate_id}`. Content addressing makes retried
679/// submissions converge on one key.
680pub fn candidate_effect_key(candidate_id: &CandidateId) -> String {
681    format!("candidate:{candidate_id}")
682}
683
684/// The derived idempotency key of an evaluation:
685/// `evaluation:{candidate_id}:{dataset_version}`. Re-evaluation against
686/// the same dataset version converges; a new dataset version is a new
687/// evaluation by construction.
688pub fn evaluation_effect_key(candidate_id: &CandidateId, dataset_version: &str) -> String {
689    format!("evaluation:{candidate_id}:{dataset_version}")
690}
691
692/// The derived idempotency key of a promotion: `promotion:{candidate_id}`
693/// (the design's mechanism decision). Retried promotions converge, and
694/// recovery re-derives the same key.
695pub fn promotion_effect_key(candidate_id: &CandidateId) -> String {
696    format!("promotion:{candidate_id}")
697}
698
699/// The derived idempotency key of a rollback:
700/// `rollback:{surface}:{candidate_id}` — one rollback per candidate per
701/// surface.
702pub fn rollback_effect_key(surface: &SurfaceKey, candidate_id: &CandidateId) -> String {
703    format!("rollback:{surface}:{candidate_id}")
704}
705
706/// The effect kind promotions derive their deterministic id under.
707pub const PROMOTION_EFFECT_KIND: &str = "candidate_promotion";
708
709/// The deterministic effect id of a candidate's promotion —
710/// [`derive_effect_id`] over the target surface (scope), the promotion
711/// kind, the candidate's content hash (input hash), and the promotion
712/// effect key. This is the id an out-of-envelope [`ApprovalToken`] must
713/// be scoped to: the scope check makes an approval for one candidate
714/// non-transferable to another, and the token's `approved_by` gives the
715/// journaled promotion its attribution.
716pub fn promotion_effect_id(candidate: &Candidate) -> EffectId {
717    derive_effect_id(
718        candidate.surface().as_str(),
719        PROMOTION_EFFECT_KIND,
720        candidate.candidate_id.as_str(),
721        Some(&promotion_effect_key(&candidate.candidate_id)),
722    )
723}
724
725// --------------------------------------------------------------------- //
726// The evaluation composition seam
727// --------------------------------------------------------------------- //
728
729/// The comparison thresholds an evaluation ran under — the deliberate
730/// mirror of `rusty-eval`'s `CompareThresholds`, serde-identical by
731/// contract: the evaluator (which links `rusty-eval`) maps one onto the
732/// other field-for-field, and the journaled payload speaks this shape so
733/// the runtime never links the eval crate (the workspace's dependency
734/// direction is `rusty-eval` → runtime, never the reverse).
735#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
736pub struct EvaluationThresholds {
737    /// Maximum tolerable absolute pass-rate drop, per assertion and per
738    /// case, before the comparison flags a regression.
739    pub max_pass_rate_drop: f64,
740
741    /// Maximum tolerable p95 latency ratio `candidate / baseline`.
742    pub max_latency_p95_ratio: f64,
743}
744
745impl Default for EvaluationThresholds {
746    /// 5-point pass-rate drop tolerance, 25% p95 latency tolerance — the
747    /// same defaults `CompareThresholds` declares.
748    fn default() -> Self {
749        Self {
750            max_pass_rate_drop: 0.05,
751            max_latency_p95_ratio: 1.25,
752        }
753    }
754}
755
756/// The comparison verdict the promotion gate reads — the deliberate
757/// mirror of the release-gate bits of `rusty-eval`'s `ComparisonReport`
758/// (`regressed` plus the target metric's movement), stated in terms the
759/// envelope's evidence thresholds consume: no regression **and**
760/// improvement on the target metric over the named dataset version.
761#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
762pub struct EvaluationVerdict {
763    /// `compare()`'s release-gate bit: any threshold breach.
764    pub regressed: bool,
765
766    /// The metric the envelope's improvement bar reads (e.g.
767    /// `run_pass_rate`, `case:{case_id}`, `assertion:{key}`).
768    pub target_metric: String,
769
770    /// The metric's baseline value, when the baseline names it.
771    #[serde(default, skip_serializing_if = "Option::is_none")]
772    pub baseline: Option<f64>,
773
774    /// The metric's candidate value, when the candidate names it.
775    #[serde(default, skip_serializing_if = "Option::is_none")]
776    pub candidate: Option<f64>,
777
778    /// `candidate - baseline` (negative is worse); absent when either
779    /// side lacks the metric — an improvement bar cannot clear on a
780    /// metric the evidence does not name.
781    #[serde(default, skip_serializing_if = "Option::is_none")]
782    pub delta: Option<f64>,
783}
784
785/// One recorded run that diverged under replay with the candidate
786/// applied: the fixture and the first disagreement, summarized (the full
787/// evidence is the replayed journal, reachable by fixture id).
788#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
789pub struct ReplayDivergence {
790    /// The replay fixture (a recorded run's identity) that diverged.
791    pub fixture_id: String,
792
793    /// The first disagreement, summarized (kind, sequence, request hash —
794    /// enough to locate it without dumping payloads).
795    pub detail: String,
796}
797
798/// The replay half of an evaluation: recorded runs re-driven with the
799/// candidate applied. Exact replay serves journaled effects, so the
800/// candidate's behavior is measured against identical evidence with zero
801/// outbound calls; divergence detection is the replay engine's own
802/// contract, consumed — not re-implemented — here.
803#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
804pub struct ReplaySummary {
805    /// Every fixture re-driven (recorded run identities), sorted for
806    /// determinism.
807    pub fixture_ids: Vec<String>,
808
809    /// How many fixtures replayed without divergence.
810    pub matched: usize,
811
812    /// Every fixture that diverged, sorted by fixture id.
813    #[serde(default, skip_serializing_if = "Vec::is_empty")]
814    pub divergences: Vec<ReplayDivergence>,
815}
816
817impl ReplaySummary {
818    /// `true` when every fixture replayed clean. The auto-promotion bar
819    /// requires it: a candidate that cannot reproduce its evidence has no
820    /// business in front of a comparison verdict.
821    pub fn is_clean(&self) -> bool {
822        self.divergences.is_empty() && self.matched == self.fixture_ids.len()
823    }
824}
825
826/// The journaled evaluation payload — the `CandidateEvaluated` event's
827/// output. The evaluation is evidence, not a log line: the verdict, the
828/// report pair, the dataset version, and the replay fixture ids, so the
829/// improvement is explainable afterward by walking ids (candidate →
830/// evaluation → reports → fixtures).
831#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
832pub struct CandidateEvaluation {
833    /// The evaluated candidate.
834    pub candidate_id: CandidateId,
835
836    /// The versioned dataset both reports ran against. Versioned, never
837    /// edited in place — the envelope's auto-promotion bar may name the
838    /// exact version a clean verdict must come from.
839    pub dataset_version: String,
840
841    /// The replay half: divergence summary plus the fixture ids.
842    pub replay: ReplaySummary,
843
844    /// The baseline experiment report, verbatim (`rusty-eval`'s
845    /// `ExperimentReport` serialized; carried as a value because the
846    /// runtime does not link the eval crate — see the module docs).
847    pub baseline_report: Value,
848
849    /// The candidate experiment report, same convention.
850    pub candidate_report: Value,
851
852    /// The comparison verdict the gate reads.
853    pub verdict: EvaluationVerdict,
854
855    /// The thresholds the comparison applied, echoed so an auditor reads
856    /// the bar the verdict was judged against, not a later default.
857    pub thresholds: EvaluationThresholds,
858
859    /// Who ran the evaluation (attribution is mandatory here too).
860    pub evaluated_by: ProvenanceAuthor,
861
862    /// When the evaluation ran.
863    pub evaluated_at: DateTime<Utc>,
864}
865
866/// What an evaluator is asked to do: run `candidate` over the declared
867/// evidence and produce the journaled [`CandidateEvaluation`].
868/// Wire-complete: the server's evaluate route accepts it as the request
869/// body.
870#[derive(Debug, Clone, Serialize, Deserialize)]
871pub struct EvaluationRequest {
872    /// The dataset version both reports must name.
873    pub dataset_version: String,
874
875    /// The metric the promotion gate reads.
876    pub target_metric: String,
877
878    /// The comparison thresholds.
879    pub thresholds: EvaluationThresholds,
880
881    /// The recorded run journals to re-drive with the candidate applied
882    /// (the replay half's evidence), already integrity-loadable.
883    pub replay_evidence: Vec<JournalSnapshot>,
884}
885
886/// The evaluation seam: composition, not duplication. The implementation
887/// builds `PreparedRun`s with the candidate applied (for `memory_set`,
888/// the candidate's records visible at their scope via
889/// [`CandidateOverlay`]; for `prompt`, the pinned prompt hash substituted
890/// via [`Candidate::apply_to_manifest`]) and drives them through the real
891/// executor — replay over [`EvaluationRequest::replay_evidence`] for the
892/// divergence half, `rusty-eval`'s `ExperimentRunner` over the versioned
893/// dataset for the report half, `compare()` for the verdict.
894///
895/// The runtime owns this trait rather than an implementation for the same
896/// reason it owns the distiller contract but not distillers (design open
897/// question 2), compounded by the workspace's dependency direction:
898/// `rusty-eval` links the runtime, never the reverse. Wave 4's release
899/// proof implements this trait over `rusty-eval`'s public API; wave 3
900/// proves the seam with scripted nodes.
901#[async_trait]
902pub trait CandidateEvaluator: Send + Sync + std::fmt::Debug {
903    /// Evaluate `candidate` against `request`'s evidence. The returned
904    /// evaluation must name the candidate and the request's dataset
905    /// version — the gate refuses mismatches.
906    async fn evaluate(
907        &self,
908        candidate: &Candidate,
909        request: &EvaluationRequest,
910    ) -> Result<CandidateEvaluation>;
911}
912
913// --------------------------------------------------------------------- //
914// Candidate application: the memory overlay
915// --------------------------------------------------------------------- //
916
917/// A `memory_set` candidate applied as a read lens over a live store:
918/// the candidate's records answer at their scope, its supersessions drop
919/// out of default retrieval, and everything else passes through. This is
920/// how evaluation (and, post-promotion, new traffic) sees candidate
921/// memory without a store migration — the candidate applied, as a store.
922///
923/// The lens is deliberately read-only: writes fail. An evaluation that
924/// writes through the candidate's lens would be mutating production
925/// memory mid-measurement — the silent-rewrite pattern the pipeline
926/// exists to forbid.
927#[derive(Debug)]
928pub struct CandidateOverlay {
929    base: Arc<dyn MemoryStore>,
930    adds: Vec<MemoryRecord>,
931    supersedes: HashSet<String>,
932}
933
934impl CandidateOverlay {
935    /// Apply `candidate` over `base`. Fails for non-`memory_set`
936    /// candidates: a candidate applies only to the surface its kind
937    /// declares.
938    pub fn new(base: Arc<dyn MemoryStore>, candidate: &Candidate) -> Result<Self> {
939        let CandidateContent::MemorySet {
940            adds, supersedes, ..
941        } = &candidate.content
942        else {
943            return Err(invalid(format!(
944                "only a `memory_set` candidate applies as a memory overlay; `{}` candidates \
945                 apply to their own surfaces",
946                candidate.kind().as_str()
947            )));
948        };
949        Ok(Self {
950            base,
951            adds: adds.clone(),
952            supersedes: supersedes.iter().cloned().collect(),
953        })
954    }
955}
956
957#[async_trait]
958impl MemoryStore for CandidateOverlay {
959    async fn put(&self, _record: &MemoryRecord) -> Result<bool> {
960        Err(invalid(
961            "the candidate overlay is a read lens: writes through it would mutate production \
962             memory mid-evaluation — the silent-rewrite pattern the candidate pipeline exists \
963             to forbid",
964        ))
965    }
966
967    async fn get(&self, memory_id: &str) -> Result<Option<MemoryRecord>> {
968        if let Some(record) = self.adds.iter().find(|r| r.memory_id == memory_id) {
969            return Ok(Some(record.clone()));
970        }
971        self.base.get(memory_id).await
972    }
973
974    async fn all(&self) -> Result<Vec<MemoryRecord>> {
975        // Merge by content address: a candidate record already in the base
976        // is the same record (identity is integrity), so the add wins by
977        // construction and nothing doubles.
978        let mut merged: Vec<MemoryRecord> = self
979            .base
980            .all()
981            .await?
982            .into_iter()
983            .filter(|record| {
984                !self
985                    .adds
986                    .iter()
987                    .any(|add| add.memory_id == record.memory_id)
988            })
989            .collect();
990        merged.extend(self.adds.iter().cloned());
991        Ok(merged)
992    }
993
994    async fn remove(&self, _memory_id: &str) -> Result<bool> {
995        Err(invalid(
996            "the candidate overlay is a read lens: deletion through it would mutate production \
997             memory mid-evaluation",
998        ))
999    }
1000
1001    async fn query(&self, query: &MemoryQuery, now: DateTime<Utc>) -> Result<Vec<MemoryRecord>> {
1002        // Core's matcher supplies every filter semantic, including the
1003        // superseded set it computes from the merged universe (the adds'
1004        // own `supersedes` fields included). The candidate's explicit
1005        // supersession list is the overlay's own contribution: drop those
1006        // ids unless the query asked for superseded records.
1007        let matched = apply_query(&self.all().await?, query, now);
1008        if query.include_superseded || self.supersedes.is_empty() {
1009            return Ok(matched);
1010        }
1011        Ok(matched
1012            .into_iter()
1013            .filter(|record| !self.supersedes.contains(&record.memory_id))
1014            .collect())
1015    }
1016}
1017
1018// --------------------------------------------------------------------- //
1019// The promotion envelope and its gate
1020// --------------------------------------------------------------------- //
1021
1022/// The evidence thresholds an auto-promotion must clear (the design's
1023/// rule): a clean replay, `compare()` showing no regression, **and**
1024/// improvement on the target metric — over the named dataset version,
1025/// when the deployment names one.
1026#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1027pub struct AutoPromotion {
1028    /// The dataset version a clean verdict must come from. `None` accepts
1029    /// the verdict's own version — honest for deployments that version
1030    /// datasets per evaluation; a named version pins the promotion to the
1031    /// exact evidence the deployment reviewed.
1032    #[serde(default, skip_serializing_if = "Option::is_none")]
1033    pub dataset_version: Option<String>,
1034
1035    /// The target-metric delta must exceed this (strictly). `0.0` is the
1036    /// design's default: any improvement clears, parity does not.
1037    pub min_improvement: f64,
1038
1039    /// The memory scopes a `memory_set` candidate may auto-promote at
1040    /// (ignored for other kinds; empty = unrestricted). The R0.8 default
1041    /// names `run` and `agent` (open question 6): wider scopes always
1042    /// require a human approval this release.
1043    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1044    pub scopes: Vec<MemoryScope>,
1045}
1046
1047/// What the envelope declares for one candidate kind. Closed enum — the
1048/// gate matches exhaustively.
1049#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1050#[serde(tag = "mode", rename_all = "snake_case")]
1051pub enum EnvelopeRule {
1052    /// May auto-promote when the evaluation clears the declared evidence
1053    /// thresholds. Inside the envelope, the envelope itself is the
1054    /// standing approval — versioned and declared, not a silent default.
1055    Auto(AutoPromotion),
1056
1057    /// Always requires a human [`ApprovalToken`] scoped to
1058    /// [`promotion_effect_id`], whatever the evidence says. The token's
1059    /// `approved_by` is the promotion's attribution.
1060    Approval,
1061
1062    /// Auto-promotes into a canary: the candidate binds to the declared
1063    /// fraction of new runs (admission picks by seeded draw —
1064    /// [`canary_admits`] — so a recorded run reproduces its assignment),
1065    /// the static version serving the rest. The evidence thresholds gate
1066    /// entry into the canary, exactly as for [`EnvelopeRule::Auto`].
1067    Canary {
1068        /// The fraction of new runs the candidate serves, in `(0, 1]`.
1069        fraction: f64,
1070        /// The evidence thresholds gating canary entry.
1071        auto: AutoPromotion,
1072    },
1073}
1074
1075/// The declared, per-deployment promotion envelope: per candidate kind,
1076/// what may promote automatically, what requires review, and what
1077/// canaries. Versioned (`envelope_version`) because the envelope is the
1078/// standing approval — a journaled promotion names the envelope version
1079/// it cleared, so the audit reads the declaration that was in force, not
1080/// a later edit.
1081///
1082/// R0.11 (wave 1) grows the envelope additively for the registry kinds:
1083/// the four new fields default to [`EnvelopeRule::Approval`] and are
1084/// absent from the wire at that default, so R0.8-era envelopes keep
1085/// deserializing and their serialization stays byte-stable — the
1086/// established contract-evolution rule. Approval is the honest default
1087/// for the new kinds: a schema tightening or an ordering change is a
1088/// contract judgment, not a metric, and a fabricated auto bar is worse
1089/// than an honest approval (the design's governance wiring).
1090#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1091pub struct PromotionEnvelope {
1092    /// The deployment-declared envelope version.
1093    pub envelope_version: String,
1094
1095    /// The rule for `prompt` candidates.
1096    pub prompt: EnvelopeRule,
1097
1098    /// The rule for `policy` candidates.
1099    pub policy: EnvelopeRule,
1100
1101    /// The rule for `memory_set` candidates.
1102    pub memory_set: EnvelopeRule,
1103
1104    /// The rule for `tool_permission` candidates.
1105    pub tool_permission: EnvelopeRule,
1106
1107    /// The rule for `tool_contract` candidates (R0.11; defaults to
1108    /// approval, absent from the wire at the default).
1109    #[serde(
1110        default = "approval_envelope_rule",
1111        skip_serializing_if = "is_approval_envelope_rule"
1112    )]
1113    pub tool_contract: EnvelopeRule,
1114
1115    /// The rule for `model_settings` candidates (R0.11; same evolution
1116    /// rule as `tool_contract`).
1117    #[serde(
1118        default = "approval_envelope_rule",
1119        skip_serializing_if = "is_approval_envelope_rule"
1120    )]
1121    pub model_settings: EnvelopeRule,
1122
1123    /// The rule for `memory_configuration` candidates (R0.11; same
1124    /// evolution rule as `tool_contract`).
1125    #[serde(
1126        default = "approval_envelope_rule",
1127        skip_serializing_if = "is_approval_envelope_rule"
1128    )]
1129    pub memory_configuration: EnvelopeRule,
1130
1131    /// The rule for `middleware_composition` candidates (R0.11; same
1132    /// evolution rule as `tool_contract`).
1133    #[serde(
1134        default = "approval_envelope_rule",
1135        skip_serializing_if = "is_approval_envelope_rule"
1136    )]
1137    pub middleware_composition: EnvelopeRule,
1138}
1139
1140/// The R0.11 additive fields' default: approval. A contract judgment
1141/// (schema, settings, composition) earns a human's name by default; a
1142/// deployment that wants evidence-gated automation declares it.
1143fn approval_envelope_rule() -> EnvelopeRule {
1144    EnvelopeRule::Approval
1145}
1146
1147/// The sparse-wire predicate for the R0.11 additive fields: approval is
1148/// the default, so an approval rule serializes as absence.
1149fn is_approval_envelope_rule(rule: &EnvelopeRule) -> bool {
1150    *rule == EnvelopeRule::Approval
1151}
1152
1153impl PromotionEnvelope {
1154    /// The R0.8 default (design open question 6): `memory_set` candidates
1155    /// at run and agent scope with a clean verdict may auto-promote;
1156    /// `prompt`, `policy`, and `tool_permission` always require an
1157    /// approval token this release. The R0.11 stance extends it: the
1158    /// registry kinds (tool contracts, model settings, memory
1159    /// configurations, middleware compositions) default to approval —
1160    /// a schema or ordering change is a contract judgment, and a
1161    /// fabricated metric is worse than an honest approval.
1162    pub fn r08_default() -> Self {
1163        Self {
1164            envelope_version: "r0.8-default".to_owned(),
1165            prompt: EnvelopeRule::Approval,
1166            policy: EnvelopeRule::Approval,
1167            memory_set: EnvelopeRule::Auto(AutoPromotion {
1168                dataset_version: None,
1169                min_improvement: 0.0,
1170                scopes: vec![MemoryScope::Run, MemoryScope::Agent],
1171            }),
1172            tool_permission: EnvelopeRule::Approval,
1173            tool_contract: EnvelopeRule::Approval,
1174            model_settings: EnvelopeRule::Approval,
1175            memory_configuration: EnvelopeRule::Approval,
1176            middleware_composition: EnvelopeRule::Approval,
1177        }
1178    }
1179
1180    /// The rule for `kind`.
1181    pub fn rule_for(&self, kind: CandidateKind) -> &EnvelopeRule {
1182        match kind {
1183            CandidateKind::Prompt => &self.prompt,
1184            CandidateKind::Policy => &self.policy,
1185            CandidateKind::MemorySet => &self.memory_set,
1186            CandidateKind::ToolPermission => &self.tool_permission,
1187            CandidateKind::ToolContract => &self.tool_contract,
1188            CandidateKind::ModelSettings => &self.model_settings,
1189            CandidateKind::MemoryConfiguration => &self.memory_configuration,
1190            CandidateKind::MiddlewareComposition => &self.middleware_composition,
1191        }
1192    }
1193
1194    /// The declaration's own validity: canary fractions in `(0, 1]` and
1195    /// improvement bars non-negative. Checked where envelopes are
1196    /// declared (deployment configuration), so a malformed envelope fails
1197    /// at startup, not at a promotion.
1198    pub fn validate(&self) -> Result<()> {
1199        for rule in [
1200            &self.prompt,
1201            &self.policy,
1202            &self.memory_set,
1203            &self.tool_permission,
1204            &self.tool_contract,
1205            &self.model_settings,
1206            &self.memory_configuration,
1207            &self.middleware_composition,
1208        ] {
1209            match rule {
1210                EnvelopeRule::Auto(auto) => check_auto(auto)?,
1211                EnvelopeRule::Canary { fraction, auto } => {
1212                    if !(fraction.is_finite() && *fraction > 0.0 && *fraction <= 1.0) {
1213                        return Err(invalid(format!(
1214                            "canary fraction must be in (0, 1], got {fraction} — a fraction \
1215                             outside the interval binds nothing or everything, and both are \
1216                             silent full promotions or silent no-ops"
1217                        )));
1218                    }
1219                    check_auto(auto)?;
1220                }
1221                EnvelopeRule::Approval => {}
1222            }
1223        }
1224        Ok(())
1225    }
1226}
1227
1228fn check_auto(auto: &AutoPromotion) -> Result<()> {
1229    if !(auto.min_improvement.is_finite() && auto.min_improvement >= 0.0) {
1230        return Err(invalid(format!(
1231            "min_improvement must be finite and non-negative, got {} — a negative bar would \
1232             auto-promote regressions, which is the one outcome the gate exists to refuse",
1233            auto.min_improvement
1234        )));
1235    }
1236    Ok(())
1237}
1238
1239/// A canary binding: the candidate serves `fraction` of new runs on its
1240/// surface, admission picking by seeded draw ([`canary_admits`]); the
1241/// static version (or the pointer's full `active`) serves the rest.
1242#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1243pub struct CanaryBinding {
1244    /// The canaried candidate.
1245    pub candidate_id: CandidateId,
1246
1247    /// The fraction of new runs the candidate serves, in `(0, 1]`.
1248    pub fraction: f64,
1249}
1250
1251/// Domain-separation prefix for [`canary_admits`] — canary draws must
1252/// never collide with effect ids, journal heads, or any other digest in
1253/// the system.
1254pub const CANARY_DRAW_DOMAIN: &str = "rusty/canary-draw/v1";
1255
1256/// The canary admission draw: whether `run_id` binds `binding`'s
1257/// candidate on `surface`.
1258///
1259/// **Seed derivation, documented (the design's reproducibility rule).**
1260/// The draw is `SHA-256` over the newline-joined tuple
1261/// `CANARY_DRAW_DOMAIN "\n" surface "\n" candidate_id "\n" run_id`,
1262/// read as a `u64` from the digest's first eight bytes (big-endian) and
1263/// compared against `fraction × u64::MAX`. Every input is journaled
1264/// evidence — the surface and candidate id are on the pointer the run
1265/// bound, the run id is the journal's own identity — so a recorded run
1266/// re-derives its assignment exactly, and the draw needs no RNG state of
1267/// its own. The candidate id's presence makes two canaries on one
1268/// surface independent draws; the run id's presence makes one canary's
1269/// assignments uniform across traffic.
1270pub fn canary_admits(binding: &CanaryBinding, surface: &SurfaceKey, run_id: &str) -> bool {
1271    if binding.fraction >= 1.0 {
1272        return true;
1273    }
1274    let material = [
1275        CANARY_DRAW_DOMAIN,
1276        surface.as_str(),
1277        binding.candidate_id.as_str(),
1278        run_id,
1279    ]
1280    .join("\n");
1281    // The first eight bytes of the digest as a big-endian u64: uniform
1282    // over the digest space, so `draw < fraction × MAX` admits a
1283    // `fraction` share of runs.
1284    let mut hasher = Sha256::new();
1285    hasher.update(material.as_bytes());
1286    let digest = hasher.finalize();
1287    let draw = u64::from_be_bytes(digest[..8].try_into().expect("eight bytes"));
1288    (draw as f64) < binding.fraction * (u64::MAX as f64)
1289}
1290
1291/// Why a promotion was refused. A dedicated error type (the
1292/// [`crate::effects::EffectViolation`] precedent): refusals are contract
1293/// outcomes surfaced to the caller, not runtime failures — and a refused
1294/// promotion changes nothing.
1295#[derive(Debug, Clone, PartialEq, Error)]
1296pub enum PromotionRefusal {
1297    /// The candidate was never evaluated. Promotion is gated on evidence;
1298    /// there is no evidence-free path, not even with an approval — a
1299    /// human approves *reviewed evidence*, never a blank check.
1300    #[error(
1301        "candidate `{candidate_id}` has no journaled evaluation: promotion is gated on \
1302         evidence — a human approves reviewed evidence, never a blank check"
1303    )]
1304    NotEvaluated {
1305        /// The candidate refused.
1306        candidate_id: CandidateId,
1307    },
1308
1309    /// The evaluation on record is not this candidate's.
1310    #[error(
1311        "evaluation names candidate `{evaluation}` but promotion was requested for \
1312         `{candidate_id}` — the evidence must be the candidate's own"
1313    )]
1314    EvaluationMismatch {
1315        /// The candidate refused.
1316        candidate_id: CandidateId,
1317        /// The candidate the journaled evaluation names.
1318        evaluation: CandidateId,
1319    },
1320
1321    /// The replay half diverged: the candidate could not reproduce its
1322    /// recorded evidence.
1323    #[error(
1324        "candidate `{candidate_id}` diverged under replay ({divergences} fixture(s)): a \
1325         candidate that cannot reproduce its evidence never auto-promotes"
1326    )]
1327    ReplayDiverged {
1328        /// The candidate refused.
1329        candidate_id: CandidateId,
1330        /// How many fixtures diverged.
1331        divergences: usize,
1332    },
1333
1334    /// `compare()` flagged a regression beyond the declared thresholds.
1335    #[error(
1336        "candidate `{candidate_id}` regressed against its baseline: the auto-promotion bar \
1337         is no regression AND improvement — the evidence failed the first half"
1338    )]
1339    EvaluationRegressed {
1340        /// The candidate refused.
1341        candidate_id: CandidateId,
1342    },
1343
1344    /// The envelope names a dataset version the evaluation did not run.
1345    #[error(
1346        "envelope requires a clean verdict over dataset `{required}` but the evaluation \
1347         ran `{evaluated}` — the promotion bar names its evidence exactly"
1348    )]
1349    DatasetVersionMismatch {
1350        /// The version the envelope names.
1351        required: String,
1352        /// The version the evaluation ran.
1353        evaluated: String,
1354    },
1355
1356    /// A `memory_set` candidate at a scope the auto rule does not cover.
1357    #[error(
1358        "memory_set candidates at `{scope:?}` scope do not auto-promote under this envelope — \
1359         the R0.8 default covers run and agent scope; wider scopes require an approval"
1360    )]
1361    ScopeNotAutoPromotable {
1362        /// The scope that fell outside the rule.
1363        scope: MemoryScope,
1364    },
1365
1366    /// The target metric did not improve past the declared bar.
1367    #[error(
1368        "target metric moved by {delta:?} but the envelope requires improvement past \
1369         {required} — parity is not improvement, and the auto bar does not clear on it"
1370    )]
1371    InsufficientImprovement {
1372        /// The observed delta (`None`: the evidence did not name the
1373        /// metric at all).
1374        delta: Option<f64>,
1375        /// The bar the envelope declared.
1376        required: f64,
1377    },
1378
1379    /// The candidate falls outside the envelope's auto paths: a human
1380    /// approval scoped to the named effect id is required.
1381    #[error(
1382        "this promotion is outside the envelope: present an approval token scoped to \
1383         effect id {effect_id} — the scope check makes an approval for one candidate \
1384         non-transferable to another"
1385    )]
1386    RequiresApproval {
1387        /// The effect id the approval must be scoped to
1388        /// ([`promotion_effect_id`]).
1389        effect_id: EffectId,
1390    },
1391
1392    /// A token was presented, but it approves a different effect id.
1393    #[error(
1394        "approval token for {presented} does not admit this promotion ({required}) — an \
1395         approval is scoped to exactly one candidate's promotion and is not transferable"
1396    )]
1397    ApprovalMismatch {
1398        /// The effect id the admission requires.
1399        required: EffectId,
1400        /// The effect id the presented token approves.
1401        presented: EffectId,
1402    },
1403}
1404
1405/// The learn plane's typed errors: address integrity, lifecycle
1406/// transitions, and promotion refusals. Refused operations change
1407/// nothing — there is no silent no-op anywhere in the pipeline.
1408#[derive(Debug, Clone, PartialEq, Error)]
1409pub enum LearnError {
1410    /// A candidate's id does not re-derive from its content — the
1411    /// tampered-candidate case, failing closed at the gate.
1412    #[error(
1413        "candidate address mismatch: id {claimed} does not re-derive from the content \
1414         (derived {derived}) — identity is integrity, and a tampered candidate fails its \
1415         own address"
1416    )]
1417    AddressMismatch {
1418        /// The id the candidate claims.
1419        claimed: CandidateId,
1420        /// The id its content derives.
1421        derived: CandidateId,
1422    },
1423
1424    /// The candidate's content could not be serialized for addressing —
1425    /// unreachable for well-formed content, surfaced rather than
1426    /// panicked.
1427    #[error("candidate content could not be addressed: {0}")]
1428    UnaddressableContent(String),
1429
1430    /// A lifecycle transition the state machine does not admit (e.g.
1431    /// promoting a candidate that was never evaluated, rolling back one
1432    /// that was never promoted).
1433    #[error(
1434        "invalid candidate transition: cannot {action} from status `{from:?}` — refused \
1435         transitions are errors, not silent no-ops"
1436    )]
1437    InvalidTransition {
1438        /// The status the transition was attempted from.
1439        from: CandidateStatus,
1440        /// The attempted transition.
1441        action: &'static str,
1442    },
1443
1444    /// A receipt presented for one candidate names another.
1445    #[error(
1446        "receipt names candidate `{named}` but the record is `{candidate_id}` — a receipt \
1447         applies to the candidate it was minted for, never to another"
1448    )]
1449    ReceiptMismatch {
1450        /// The candidate the record holds.
1451        candidate_id: CandidateId,
1452        /// The candidate the receipt names.
1453        named: CandidateId,
1454    },
1455
1456    /// The promotion gate refused.
1457    #[error("{0}")]
1458    Refused(#[from] PromotionRefusal),
1459}
1460
1461/// The promotion gate's positive decision: the authority the promotion
1462/// clears under, journaled on the receipt — the envelope version (the
1463/// standing approval) or the token's `approved_by` — plus the canary
1464/// binding, when the promotion is a canary.
1465#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1466pub struct PromotionDecision {
1467    /// Who authorized the promotion.
1468    pub authority: PromotionAuthority,
1469
1470    /// The canary binding, when the envelope declared a canary.
1471    #[serde(default, skip_serializing_if = "Option::is_none")]
1472    pub canary: Option<CanaryBinding>,
1473}
1474
1475/// The authority a promotion cleared under. Closed enum — the journaled
1476/// attribution.
1477#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1478#[serde(tag = "authority", rename_all = "snake_case")]
1479pub enum PromotionAuthority {
1480    /// The envelope's auto path cleared: the envelope itself is the
1481    /// standing approval, and the journaled version is the declaration
1482    /// that was in force.
1483    Envelope {
1484        /// The envelope version that admitted the promotion.
1485        envelope_version: String,
1486    },
1487    /// A human approved out-of-envelope: the token's `approved_by` is the
1488    /// attribution.
1489    Approval {
1490        /// Who approved (the token's `approved_by`).
1491        approved_by: String,
1492    },
1493}
1494
1495/// The promotion gate (the design's promote stage), a pure function over
1496/// the envelope, the candidate, its journaled evaluation, and an optional
1497/// approval token.
1498///
1499/// Order of decisions: integrity first ([`Candidate::verify_address`] —
1500/// a tampered candidate fails closed before any policy reads it), then
1501/// evidence (a journaled evaluation of *this* candidate must exist —
1502/// approvals review evidence, they never replace it), then the envelope
1503/// rule for the candidate's kind: auto paths check the evidence
1504/// thresholds (clean replay, no regression, improvement past the
1505/// declared bar, over the named dataset version, at an admitted scope),
1506/// the approval path requires a token scoped to [`promotion_effect_id`].
1507/// Refusal is a typed [`PromotionRefusal`]; nothing here mutates
1508/// anything.
1509pub fn admit_promotion(
1510    envelope: &PromotionEnvelope,
1511    candidate: &Candidate,
1512    evaluation: Option<&CandidateEvaluation>,
1513    approval: Option<&ApprovalToken>,
1514) -> std::result::Result<PromotionDecision, LearnError> {
1515    candidate.verify_address()?;
1516    let evaluation = evaluation.ok_or(PromotionRefusal::NotEvaluated {
1517        candidate_id: candidate.candidate_id.clone(),
1518    })?;
1519    if evaluation.candidate_id != candidate.candidate_id {
1520        return Err(PromotionRefusal::EvaluationMismatch {
1521            candidate_id: candidate.candidate_id.clone(),
1522            evaluation: evaluation.candidate_id.clone(),
1523        }
1524        .into());
1525    }
1526    match envelope.rule_for(candidate.kind()) {
1527        EnvelopeRule::Auto(auto) => {
1528            check_evidence_bar(auto, candidate, evaluation)?;
1529            Ok(PromotionDecision {
1530                authority: PromotionAuthority::Envelope {
1531                    envelope_version: envelope.envelope_version.clone(),
1532                },
1533                canary: None,
1534            })
1535        }
1536        EnvelopeRule::Canary { fraction, auto } => {
1537            check_evidence_bar(auto, candidate, evaluation)?;
1538            Ok(PromotionDecision {
1539                authority: PromotionAuthority::Envelope {
1540                    envelope_version: envelope.envelope_version.clone(),
1541                },
1542                canary: Some(CanaryBinding {
1543                    candidate_id: candidate.candidate_id.clone(),
1544                    fraction: *fraction,
1545                }),
1546            })
1547        }
1548        EnvelopeRule::Approval => {
1549            let required = promotion_effect_id(candidate);
1550            let token = approval.ok_or(PromotionRefusal::RequiresApproval {
1551                effect_id: required.clone(),
1552            })?;
1553            if !token.admits(&required) {
1554                return Err(PromotionRefusal::ApprovalMismatch {
1555                    required,
1556                    presented: token.effect_id().clone(),
1557                }
1558                .into());
1559            }
1560            Ok(PromotionDecision {
1561                authority: PromotionAuthority::Approval {
1562                    approved_by: token.approved_by().to_owned(),
1563                },
1564                canary: None,
1565            })
1566        }
1567    }
1568}
1569
1570/// The auto paths' evidence bar (the design's thresholds): clean replay,
1571/// no regression, improvement past the declared bar on the target
1572/// metric, over the named dataset version, at an admitted scope.
1573fn check_evidence_bar(
1574    auto: &AutoPromotion,
1575    candidate: &Candidate,
1576    evaluation: &CandidateEvaluation,
1577) -> std::result::Result<(), LearnError> {
1578    if !evaluation.replay.is_clean() {
1579        return Err(PromotionRefusal::ReplayDiverged {
1580            candidate_id: candidate.candidate_id.clone(),
1581            divergences: evaluation.replay.divergences.len(),
1582        }
1583        .into());
1584    }
1585    if evaluation.verdict.regressed {
1586        return Err(PromotionRefusal::EvaluationRegressed {
1587            candidate_id: candidate.candidate_id.clone(),
1588        }
1589        .into());
1590    }
1591    if let Some(required) = &auto.dataset_version {
1592        if required != &evaluation.dataset_version {
1593            return Err(PromotionRefusal::DatasetVersionMismatch {
1594                required: required.clone(),
1595                evaluated: evaluation.dataset_version.clone(),
1596            }
1597            .into());
1598        }
1599    }
1600    if let CandidateContent::MemorySet { scope, .. } = &candidate.content {
1601        if !auto.scopes.is_empty() && !auto.scopes.contains(&scope.scope) {
1602            return Err(PromotionRefusal::ScopeNotAutoPromotable { scope: scope.scope }.into());
1603        }
1604    }
1605    let clears = evaluation
1606        .verdict
1607        .delta
1608        .is_some_and(|delta| delta > auto.min_improvement);
1609    if !clears {
1610        return Err(PromotionRefusal::InsufficientImprovement {
1611            delta: evaluation.verdict.delta,
1612            required: auto.min_improvement,
1613        }
1614        .into());
1615    }
1616    Ok(())
1617}
1618
1619// --------------------------------------------------------------------- //
1620// The lifecycle record and the active-version pointer
1621// --------------------------------------------------------------------- //
1622
1623/// Where a candidate is in its lifecycle. Closed enum; transitions are
1624/// journaled events, and refused transitions are errors.
1625#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
1626#[serde(rename_all = "snake_case")]
1627pub enum CandidateStatus {
1628    /// Distilled, not yet evaluated.
1629    Created,
1630    /// Evaluated against recorded evidence; the evaluation is on record.
1631    Evaluated,
1632    /// Promoted: the surface's pointer names this candidate (fully, or as
1633    /// the canary).
1634    Promoted,
1635    /// Rolled back: the pointer re-pointed away from this candidate.
1636    RolledBack,
1637}
1638
1639/// The journaled promotion receipt — the `CandidatePromoted` event's
1640/// output payload. Plays the effect receipt's role for the learning
1641/// plane: the durable, attributable confirmation that the pointer moved.
1642#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1643pub struct PromotionReceipt {
1644    /// The promoted candidate.
1645    pub candidate_id: CandidateId,
1646
1647    /// The surface whose pointer moved.
1648    pub surface: SurfaceKey,
1649
1650    /// The pointer's full-traffic value before the move (`None`: the
1651    /// static version served). Rollback re-points to exactly this — the
1652    /// byte-exactness comes from candidates being content-addressed and
1653    /// immutable, so `previous` *is* the version that served, not a
1654    /// reconstruction of it.
1655    #[serde(default, skip_serializing_if = "Option::is_none")]
1656    pub previous: Option<CandidateId>,
1657
1658    /// The gate's decision: the authority and the canary binding.
1659    pub decision: PromotionDecision,
1660
1661    /// When the promotion executed.
1662    pub promoted_at: DateTime<Utc>,
1663}
1664
1665/// The journaled rollback receipt — the `CandidateRolledBack` event's
1666/// output payload.
1667#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1668pub struct RollbackReceipt {
1669    /// The surface whose pointer re-pointed.
1670    pub surface: SurfaceKey,
1671
1672    /// The candidate rolled back (the version that was serving).
1673    pub from: CandidateId,
1674
1675    /// The candidate re-pointed to (`None`: the static version serves
1676    /// again — revert-to-default is always a legal rollback).
1677    #[serde(default, skip_serializing_if = "Option::is_none")]
1678    pub to: Option<CandidateId>,
1679
1680    /// The causing evidence: what prompted the rollback (a drift
1681    /// observation's journal ids, an operator's statement naming the
1682    /// evidence). Free text by design — wave 4's drift monitor will
1683    /// write it with the same shape operators use now.
1684    pub cause: String,
1685
1686    /// When the rollback executed.
1687    pub rolled_back_at: DateTime<Utc>,
1688}
1689
1690/// A candidate and its lifecycle state: the store row both server
1691/// backends persist. Transitions go through the `apply_*` methods, which
1692/// enforce the state machine (created → evaluated → promoted → rolled
1693/// back) and refuse everything else as a typed error — the store trusts
1694/// what the gate admitted, exactly as the memory store trusts the write
1695/// gate.
1696#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1697pub struct CandidateRecord {
1698    /// The candidate itself (immutable).
1699    pub candidate: Candidate,
1700
1701    /// Where it is in its lifecycle.
1702    pub status: CandidateStatus,
1703
1704    /// The journaled evaluation (set on evaluate; replaced on
1705    /// re-evaluation — a new dataset version is a new evaluation).
1706    #[serde(default, skip_serializing_if = "Option::is_none")]
1707    pub evaluation: Option<CandidateEvaluation>,
1708
1709    /// The journaled promotion receipt (set on promote).
1710    #[serde(default, skip_serializing_if = "Option::is_none")]
1711    pub promotion: Option<PromotionReceipt>,
1712
1713    /// The journaled rollback receipt (set on rollback).
1714    #[serde(default, skip_serializing_if = "Option::is_none")]
1715    pub rollback: Option<RollbackReceipt>,
1716}
1717
1718impl CandidateRecord {
1719    /// A freshly created candidate.
1720    pub fn new(candidate: Candidate) -> Self {
1721        Self {
1722            candidate,
1723            status: CandidateStatus::Created,
1724            evaluation: None,
1725            promotion: None,
1726            rollback: None,
1727        }
1728    }
1729
1730    /// The candidate's id.
1731    pub fn candidate_id(&self) -> &CandidateId {
1732        &self.candidate.candidate_id
1733    }
1734
1735    /// Record an evaluation: `created → evaluated`, or `evaluated →
1736    /// evaluated` for re-evaluation (a new dataset version is a new
1737    /// evaluation; the effect key names both). Refused from `promoted`
1738    /// and `rolled_back`: re-evaluating a settled candidate reads as a
1739    /// new distillation, and the model keeps that honest by requiring
1740    /// one.
1741    pub fn apply_evaluation(
1742        &mut self,
1743        evaluation: CandidateEvaluation,
1744    ) -> std::result::Result<(), LearnError> {
1745        match self.status {
1746            CandidateStatus::Created | CandidateStatus::Evaluated => {}
1747            other => {
1748                return Err(LearnError::InvalidTransition {
1749                    from: other,
1750                    action: "evaluate",
1751                })
1752            }
1753        }
1754        if evaluation.candidate_id != self.candidate.candidate_id {
1755            return Err(PromotionRefusal::EvaluationMismatch {
1756                candidate_id: self.candidate.candidate_id.clone(),
1757                evaluation: evaluation.candidate_id,
1758            }
1759            .into());
1760        }
1761        self.evaluation = Some(evaluation);
1762        self.status = CandidateStatus::Evaluated;
1763        Ok(())
1764    }
1765
1766    /// Record a promotion: `evaluated → promoted`. The gate
1767    /// ([`admit_promotion`]) must already have cleared — this method
1768    /// enforces the state machine, not the evidence bar.
1769    pub fn apply_promotion(
1770        &mut self,
1771        receipt: PromotionReceipt,
1772    ) -> std::result::Result<(), LearnError> {
1773        if self.status != CandidateStatus::Evaluated {
1774            return Err(LearnError::InvalidTransition {
1775                from: self.status,
1776                action: "promote",
1777            });
1778        }
1779        if receipt.candidate_id != self.candidate.candidate_id {
1780            return Err(LearnError::ReceiptMismatch {
1781                candidate_id: self.candidate.candidate_id.clone(),
1782                named: receipt.candidate_id,
1783            });
1784        }
1785        self.promotion = Some(receipt);
1786        self.status = CandidateStatus::Promoted;
1787        Ok(())
1788    }
1789
1790    /// Record a rollback: `promoted → rolled_back`.
1791    pub fn apply_rollback(
1792        &mut self,
1793        receipt: RollbackReceipt,
1794    ) -> std::result::Result<(), LearnError> {
1795        if self.status != CandidateStatus::Promoted {
1796            return Err(LearnError::InvalidTransition {
1797                from: self.status,
1798                action: "roll back",
1799            });
1800        }
1801        if receipt.from != self.candidate.candidate_id {
1802            return Err(LearnError::ReceiptMismatch {
1803                candidate_id: self.candidate.candidate_id.clone(),
1804                named: receipt.from,
1805            });
1806        }
1807        self.rollback = Some(receipt);
1808        self.status = CandidateStatus::RolledBack;
1809        Ok(())
1810    }
1811}
1812
1813/// The active version of one production surface: an immutable-pointer
1814/// move away from any version that ever served.
1815///
1816/// Two slots, exactly the design's canary shape: `active` is the
1817/// full-traffic version (`None` — the static version serves, the
1818/// documented floor); `canary` binds one candidate to a declared fraction
1819/// of new runs while `active` serves the rest. New runs bind the pointer
1820/// at admission (the canary by seeded draw — [`canary_admits`]);
1821/// in-flight runs keep the version their checkpoint header pins, the same
1822/// conservatism as worker-version pinning and manifest pinning.
1823#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1824pub struct VersionPointer {
1825    /// The surface this pointer governs.
1826    pub surface: SurfaceKey,
1827
1828    /// The full-traffic candidate (`None`: the static version serves).
1829    #[serde(default, skip_serializing_if = "Option::is_none")]
1830    pub active: Option<CandidateId>,
1831
1832    /// The canary binding, when one is declared.
1833    #[serde(default, skip_serializing_if = "Option::is_none")]
1834    pub canary: Option<CanaryBinding>,
1835}
1836
1837impl VersionPointer {
1838    /// A pointer with nothing promoted: the static version serves.
1839    pub fn new(surface: SurfaceKey) -> Self {
1840        Self {
1841            surface,
1842            active: None,
1843            canary: None,
1844        }
1845    }
1846
1847    /// The pointer after a promotion: a canary promotion binds the
1848    /// candidate to its fraction (the full-traffic version keeps serving
1849    /// the rest); a full promotion moves `active` and clears any canary —
1850    /// a full promotion supersedes the experiment it graduated from.
1851    pub fn promoted(&self, receipt: &PromotionReceipt) -> VersionPointer {
1852        let mut next = self.clone();
1853        if let Some(binding) = &receipt.decision.canary {
1854            next.canary = Some(binding.clone());
1855        } else {
1856            next.active = Some(receipt.candidate_id.clone());
1857            next.canary = None;
1858        }
1859        next
1860    }
1861
1862    /// The pointer after a rollback: rolling back the full-traffic
1863    /// version re-points `active` to the receipt's `to`; rolling back the
1864    /// canary clears the binding. The caller validates that `from` is the
1865    /// serving version before building the receipt — this is the move,
1866    /// not the check.
1867    pub fn rolled_back(&self, receipt: &RollbackReceipt) -> VersionPointer {
1868        let mut next = self.clone();
1869        if self.active.as_ref() == Some(&receipt.from) {
1870            next.active = receipt.to.clone();
1871        }
1872        if self
1873            .canary
1874            .as_ref()
1875            .is_some_and(|binding| binding.candidate_id == receipt.from)
1876        {
1877            next.canary = None;
1878        }
1879        next
1880    }
1881}
1882
1883// --------------------------------------------------------------------- //
1884// R0.10 wave 3: the learned retry/timeout families
1885//
1886// Three pieces, all consuming the same journaled evidence:
1887//
1888// - **Distillation** ([`distill_retry_parameters`],
1889//   [`distill_timeout_parameters`]) — closed-form learners that read
1890//   `DecisionEvent`s and effect events and emit family parameter sets.
1891//   The fitting is a grid search over declared envelopes, per design open
1892//   question 1: the runtime owns small closed-form scorers serialized as
1893//   the policy's parameters; the decision path stays a lookup.
1894// - **The twin-backed evaluator** ([`TwinCandidateEvaluator`]) — the
1895//   `CandidateEvaluator` seam's policy-candidate implementation: replay
1896//   the evidence span's fixtures with the candidate shadowing nothing and
1897//   acting head-to-head against the floor on identical seeds and fault
1898//   schedules, then verdict. A candidate that loses to the floor produces
1899//   a regressed verdict, and the gate refuses it — promotion through the
1900//   pipeline, never around it.
1901// - **Drift detection** ([`detect_policy_drift`]) — the promoted
1902//   version's journaled outcomes against the baseline its promotion
1903//   evaluation recorded; the revert itself is one activation of
1904//   `static-v0` away (server side).
1905// --------------------------------------------------------------------- //
1906
1907use crate::durable::ErrorClass;
1908use crate::record::{
1909    derive_policy_version, BackoffParameters, DecisionAction, DecisionEvent, DecisionOutcome,
1910    Effect, EventStatus, ExecutorPolicy, PolicyVersion, RetryPolicyParameters, RunEvent,
1911    TimeoutPolicyParameters,
1912};
1913use crate::twin::{
1914    percentile, FaultSchedule, ParameterizedPolicy, Twin, TwinMetrics, TwinPolicy, TwinRunConfig,
1915    DEFAULT_TIMEOUT_LADDER,
1916};
1917
1918/// The charged cost of a dead-lettered item in the retry learner's model,
1919/// in milliseconds: the lease boundary — what a task that never
1920/// recovers costs the run before the queue's worst-case discovery. The
1921/// same accounting the Wave 1 experiment and the twin apply.
1922const DEAD_LETTER_PENALTY_MS: u64 = crate::durable::MAX_RETRY_DELAY_MS;
1923
1924/// How the retry distiller fits per-class schedules (R0.10 wave 3).
1925///
1926/// The grid is the learner's whole search space — closed-form scores over
1927/// declared values, so the fitted policy is inspectable as data and the
1928/// fitting itself is deterministic.
1929#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1930pub struct RetryLearningConfig {
1931    /// Minimum evidence (retries observed plus terminal outcomes) before a
1932    /// class earns its own entry. Below it the class keeps the floor —
1933    /// sparse evidence must not produce confident policy.
1934    pub min_samples: usize,
1935
1936    /// The estimated wall-time margin over the floor a candidate schedule
1937    /// must clear to be emitted, in milliseconds. The Wave 1 experiment's
1938    /// published scar is that a cheap per-class table *underperformed* the
1939    /// floor's jittered exponential on latency; the margin is what keeps
1940    /// a marginal fit from demoting the floor.
1941    pub min_improvement_ms: u64,
1942
1943    /// Candidate backoff bases, in milliseconds.
1944    pub base_grid_ms: Vec<u64>,
1945
1946    /// Candidate backoff caps, in milliseconds.
1947    pub cap_grid_ms: Vec<u64>,
1948
1949    /// Candidate attempt budgets.
1950    pub max_attempts_grid: Vec<u32>,
1951}
1952
1953impl Default for RetryLearningConfig {
1954    fn default() -> Self {
1955        Self {
1956            min_samples: 4,
1957            min_improvement_ms: 2_000,
1958            base_grid_ms: vec![100, 250, 500, 1_000, 2_000],
1959            cap_grid_ms: vec![30_000, 120_000, 300_000],
1960            max_attempts_grid: vec![1, 2, 3, 5],
1961        }
1962    }
1963}
1964
1965/// One class's distilled retry evidence.
1966#[derive(Debug, Default)]
1967struct ClassEvidence {
1968    /// Decisions that selected `Retry`.
1969    retries: u64,
1970    /// Decisions journaled with a success outcome.
1971    successes: u64,
1972    /// Decisions journaled with a failure outcome (terminal: dead-letter
1973    /// or outright fail).
1974    failures: u64,
1975    /// Callee-supplied `Retry-After` floors observed at decision time.
1976    retry_after_ms: Vec<u64>,
1977}
1978
1979/// The estimated expected cost of one schedule on one class's evidence, in
1980/// milliseconds: expected backoff wall before recovery, plus the
1981/// dead-letter penalty weighted by the probability the budget runs out.
1982/// `p` is the estimated per-retry success probability; `retry_after` is
1983/// the world's own floor on any delay (a delay shorter than the callee's
1984/// `Retry-After` is not a shorter delay — it is the callee's delay).
1985fn retry_schedule_score(
1986    base_ms: u64,
1987    cap_ms: u64,
1988    max_attempts: u32,
1989    p: f64,
1990    retry_after: u64,
1991) -> f64 {
1992    let mut wall = 0.0;
1993    let mut survival = 1.0;
1994    for k in 0..max_attempts {
1995        let mean_delay =
1996            ((base_ms.saturating_mul(1u64 << k.min(20))).min(cap_ms) / 2).max(retry_after) as f64;
1997        wall += survival * mean_delay;
1998        survival *= 1.0 - p;
1999    }
2000    wall + survival * DEAD_LETTER_PENALTY_MS as f64
2001}
2002
2003/// Distill the retry family's parameters from journaled retry
2004/// [`DecisionEvent`]s (R0.10 wave 3).
2005///
2006/// What is learned, per error class with sufficient evidence: the backoff
2007/// base and cap and the attempt budget that minimize expected wall-to-
2008/// recovery charged with dead-letter risk — **never the schedule's
2009/// shape** (full jitter over a doubling window is the floor's; Wave 1's
2010/// scar is that fixed per-class delays lose to it), and never the gates.
2011/// A class whose failures never turned into completions earns the
2012/// permanent-failure stance (`max_attempts: 1` — abort after the first
2013/// failure, the design's "earlier abort under permanent ones"); a class
2014/// whose best grid score does not beat the floor's by
2015/// [`RetryLearningConfig::min_improvement_ms`] earns nothing — the floor
2016/// decides for it. The returned set carries the floor's flat schedule;
2017/// `per_class` is `None` when no class cleared the margin, in which case
2018/// the honest next step is no candidate at all.
2019pub fn distill_retry_parameters(
2020    events: &[DecisionEvent],
2021    config: &RetryLearningConfig,
2022) -> RetryPolicyParameters {
2023    let floor = ExecutorPolicy::static_v0().retry;
2024    let mut classes: std::collections::BTreeMap<ErrorClass, ClassEvidence> =
2025        std::collections::BTreeMap::new();
2026    for event in events {
2027        if event.family != crate::record::DecisionFamily::Retry {
2028            continue;
2029        }
2030        let class = event
2031            .features
2032            .get("failure_class")
2033            .and_then(|value| serde_json::from_value(value.clone()).ok())
2034            .unwrap_or(ErrorClass::Unknown);
2035        let evidence = classes.entry(class).or_default();
2036        if matches!(event.selected, DecisionAction::Retry { .. }) {
2037            evidence.retries += 1;
2038        }
2039        match event.outcome {
2040            Some(DecisionOutcome::Success) => evidence.successes += 1,
2041            Some(DecisionOutcome::Failure) => evidence.failures += 1,
2042            _ => {}
2043        }
2044        if let Some(retry_after) = event
2045            .features
2046            .get("retry_after_ms")
2047            .and_then(serde_json::Value::as_u64)
2048        {
2049            evidence.retry_after_ms.push(retry_after);
2050        }
2051    }
2052
2053    let mut table = std::collections::BTreeMap::new();
2054    for (class, evidence) in &classes {
2055        let total = evidence.retries + evidence.failures;
2056        if (total as usize) < config.min_samples {
2057            continue;
2058        }
2059        // A class with retries observed but no recorded success estimates
2060        // at the boundary — the permanent-failure stance — only when the
2061        // failures are themselves evidence (terminal outcomes), never on
2062        // absence alone.
2063        if evidence.successes == 0 && evidence.retries > 0 {
2064            if evidence.failures >= config.min_samples as u64 {
2065                table.insert(
2066                    *class,
2067                    BackoffParameters {
2068                        base_delay_ms: floor.base_delay_ms,
2069                        max_delay_ms: floor.max_delay_ms,
2070                        max_attempts: 1,
2071                    },
2072                );
2073            }
2074            continue;
2075        }
2076        if evidence.retries == 0 || evidence.successes == 0 {
2077            continue;
2078        }
2079        let p = evidence.successes as f64 / evidence.retries as f64;
2080        let retry_after = percentile(&evidence.retry_after_ms, 50.0);
2081        let floor_score = retry_schedule_score(
2082            floor.base_delay_ms,
2083            floor.max_delay_ms,
2084            floor.max_attempts,
2085            p,
2086            retry_after,
2087        );
2088        let mut best: Option<(f64, BackoffParameters)> = None;
2089        for &base in &config.base_grid_ms {
2090            for &cap in &config.cap_grid_ms {
2091                if base == 0 || base > cap {
2092                    continue;
2093                }
2094                for &max_attempts in &config.max_attempts_grid {
2095                    let score = retry_schedule_score(base, cap, max_attempts, p, retry_after);
2096                    let candidate = BackoffParameters {
2097                        base_delay_ms: base,
2098                        max_delay_ms: cap,
2099                        max_attempts,
2100                    };
2101                    if best
2102                        .as_ref()
2103                        .is_none_or(|(best_score, _)| score < *best_score)
2104                    {
2105                        best = Some((score, candidate));
2106                    }
2107                }
2108            }
2109        }
2110        if let Some((score, schedule)) = best {
2111            if floor_score - score >= config.min_improvement_ms as f64 {
2112                table.insert(*class, schedule);
2113            }
2114        }
2115    }
2116
2117    RetryPolicyParameters {
2118        per_class: if table.is_empty() { None } else { Some(table) },
2119        ..floor
2120    }
2121}
2122
2123/// How the timeout distiller fits per-callee bounds (R0.10 wave 3).
2124#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
2125pub struct TimeoutLearningConfig {
2126    /// Minimum completions a callee must have journaled before a bound is
2127    /// fit to it. Below it the callee keeps no bound — sparse evidence
2128    /// must not produce confident policy.
2129    pub min_samples: usize,
2130
2131    /// The largest premature-abort fraction a bound may carry: the share
2132    /// of journaled completions that ran longer than the bound. The Wave
2133    /// 1 scar — a p99-plus-margin bound prematurely aborting heavy-tailed
2134    /// work — is a percentile *estimate* multiplied by a constant missing
2135    /// the tail mass the estimate cannot see; reading the abort fraction
2136    /// off the empirical distribution directly is the fix, and when no
2137    /// rung satisfies the tolerance the learner abstains (the floor keeps
2138    /// the callee) rather than shipping a bound that fails
2139    /// non-inferiority.
2140    pub abort_tolerance: f64,
2141
2142    /// The ladder the fitted bounds are chosen from, ascending. The top
2143    /// rung models "no bound in force" and is never emitted — a bound
2144    /// equal to it reclaims nothing the floor does not.
2145    pub ladder: Vec<u64>,
2146}
2147
2148impl Default for TimeoutLearningConfig {
2149    fn default() -> Self {
2150        Self {
2151            min_samples: 16,
2152            abort_tolerance: 0.01,
2153            ladder: DEFAULT_TIMEOUT_LADDER.to_vec(),
2154        }
2155    }
2156}
2157
2158/// Distill the timeout family's parameters from journaled effect events
2159/// (R0.10 wave 3). The callee identity is the event's `node_id`; only
2160/// completed calls (status `Ok` with a measured latency) are evidence —
2161/// a failure's latency says nothing about how long success takes.
2162///
2163/// Per callee: the smallest ladder rung whose empirical premature-abort
2164/// fraction (the share of completions that ran longer than the rung) is
2165/// within [`TimeoutLearningConfig::abort_tolerance`]. Callees with
2166/// insufficient evidence, with no qualifying rung (a tail heavier than
2167/// the ladder — the Wave 1 failure mode, abstained from rather than
2168/// shipped), or whose qualifying rung is the ladder's top get no entry.
2169/// `default_millis` stays `None` — the floor's stance for every callee
2170/// the evidence did not speak for; `max_millis` pins the ladder's top as
2171/// the declared ceiling when any entry exists.
2172pub fn distill_timeout_parameters(
2173    events: &[RunEvent],
2174    config: &TimeoutLearningConfig,
2175) -> TimeoutPolicyParameters {
2176    let mut latencies: std::collections::BTreeMap<String, Vec<u64>> =
2177        std::collections::BTreeMap::new();
2178    for event in events {
2179        if event.status != EventStatus::Ok {
2180            continue;
2181        }
2182        let (Some(callee), Some(latency)) = (event.node_id.clone(), event.latency_ms) else {
2183            continue;
2184        };
2185        latencies.entry(callee).or_default().push(latency);
2186    }
2187
2188    let mut table = std::collections::BTreeMap::new();
2189    let top = config.ladder.last().copied().unwrap_or(u64::MAX);
2190    for (callee, samples) in &latencies {
2191        if samples.len() < config.min_samples {
2192            continue;
2193        }
2194        let bound = config.ladder.iter().copied().find(|rung| {
2195            let aborted = samples.iter().filter(|latency| *latency > rung).count();
2196            (aborted as f64 / samples.len() as f64) <= config.abort_tolerance
2197        });
2198        match bound {
2199            Some(rung) if rung < top => {
2200                table.insert(callee.clone(), rung);
2201            }
2202            _ => {}
2203        }
2204    }
2205
2206    TimeoutPolicyParameters {
2207        default_millis: None,
2208        max_millis: if table.is_empty() { None } else { Some(top) },
2209        per_callee: if table.is_empty() { None } else { Some(table) },
2210    }
2211}
2212
2213/// The twin-backed [`CandidateEvaluator`] for `policy` candidates (R0.10
2214/// wave 3): the governance wiring's "evaluation happens in the twin",
2215/// landed. Every fixture in the request's evidence span is re-executed
2216/// twice on the same seed and fault schedule — the floor acting, then the
2217/// candidate's parameters acting through [`ParameterizedPolicy`] — and the
2218/// verdict is computed over the paired [`TwinMetrics`]: **non-inferior
2219/// completion**
2220/// (the release proof's constraint, applied at the gate) and improvement
2221/// on the request's target metric.
2222///
2223/// Verdict conventions, stated precisely: `regressed` is set when the
2224/// candidate's completion rate falls below the floor's by more than the
2225/// declared completion tolerance (see
2226/// [`TwinCandidateEvaluator::with_completion_tolerance`]) — on any single
2227/// fixture or in aggregate; `delta` is signed so that positive is better
2228/// on the named metric (for cost and latency metrics, lower is better,
2229/// so `delta = baseline − candidate`), keeping [`EvaluationVerdict`]'s
2230/// "negative is worse" invariant true for the gate. Both reports carry
2231/// every fixture's [`TwinReport`](crate::twin::TwinReport), so the
2232/// twin's validity bound travels with the evaluation (design open
2233/// question 5).
2234///
2235/// Determinism is the twin's own: same fixtures, same seed, same fault
2236/// schedule ⇒ the same metrics and the same verdict.
2237#[derive(Debug)]
2238pub struct TwinCandidateEvaluator {
2239    seed: u64,
2240    faults: FaultSchedule,
2241    workers: Vec<String>,
2242    max_attempts: u32,
2243    completion_tolerance: f64,
2244    evaluated_by: ProvenanceAuthor,
2245}
2246
2247impl TwinCandidateEvaluator {
2248    /// An evaluator drawing from `seed`, attributing every evaluation to
2249    /// `evaluated_by`, over an unfaulted recorded world, one worker, the
2250    /// floor's attempt budget, and strict completion parity (tolerance 0).
2251    pub fn new(seed: u64, evaluated_by: ProvenanceAuthor) -> Self {
2252        Self {
2253            seed,
2254            faults: FaultSchedule::new(seed),
2255            workers: vec!["worker-0".to_owned()],
2256            max_attempts: 3,
2257            completion_tolerance: 0.0,
2258            evaluated_by,
2259        }
2260    }
2261
2262    /// Builder-style: evaluate against this fault schedule — the faults
2263    /// rarer than any recorded window contains, which is the twin's
2264    /// reason to exist.
2265    pub fn with_faults(mut self, faults: FaultSchedule) -> Self {
2266        self.faults = faults;
2267        self
2268    }
2269
2270    /// Builder-style: declare the worker pool placement ranks.
2271    pub fn with_workers(mut self, workers: impl IntoIterator<Item = impl Into<String>>) -> Self {
2272        self.workers = workers.into_iter().map(Into::into).collect();
2273        self
2274    }
2275
2276    /// Builder-style: the attempt budget the world allows (a learned
2277    /// policy may narrow it, never widen it).
2278    pub fn with_max_attempts(mut self, max_attempts: u32) -> Self {
2279        self.max_attempts = max_attempts;
2280        self
2281    }
2282
2283    /// Builder-style: the completion-rate band within which the candidate
2284    /// is non-inferior. Zero is the honest default for a mechanical
2285    /// family: identical completion is achievable, so parity is the bar.
2286    pub fn with_completion_tolerance(mut self, tolerance: f64) -> Self {
2287        self.completion_tolerance = tolerance;
2288        self
2289    }
2290}
2291
2292/// Per-arm aggregates over the fixture set, computed once and shared by
2293/// the verdict and the reports.
2294#[derive(Debug, Clone, Copy, Default)]
2295struct ArmAggregate {
2296    items: usize,
2297    completed: usize,
2298    dead_lettered: usize,
2299    attempts: u64,
2300    cost_usd: f64,
2301    wall_time_ms: u64,
2302    latency_p95_ms: u64,
2303    runs: usize,
2304}
2305
2306impl ArmAggregate {
2307    fn fold(&mut self, metrics: &TwinMetrics) {
2308        self.items += metrics.items;
2309        self.completed += metrics.completed;
2310        self.dead_lettered += metrics.dead_lettered;
2311        self.attempts += metrics.attempts;
2312        self.cost_usd += metrics.cost_usd;
2313        self.wall_time_ms += metrics.wall_time_ms;
2314        self.latency_p95_ms = self.latency_p95_ms.max(metrics.item_latency_p95_ms);
2315        self.runs += 1;
2316    }
2317
2318    fn completion_rate(&self) -> f64 {
2319        if self.items == 0 {
2320            0.0
2321        } else {
2322            self.completed as f64 / self.items as f64
2323        }
2324    }
2325
2326    fn dead_letter_rate(&self) -> f64 {
2327        if self.items == 0 {
2328            0.0
2329        } else {
2330            self.dead_lettered as f64 / self.items as f64
2331        }
2332    }
2333
2334    fn mean_wall_ms(&self) -> f64 {
2335        if self.runs == 0 {
2336            0.0
2337        } else {
2338            self.wall_time_ms as f64 / self.runs as f64
2339        }
2340    }
2341
2342    /// The serialized aggregate both reports carry — also the shape
2343    /// [`DriftBaseline::from_twin_report`] reads back.
2344    fn as_value(&self) -> Value {
2345        serde_json::json!({
2346            "items": self.items,
2347            "completed": self.completed,
2348            "dead_lettered": self.dead_lettered,
2349            "attempts": self.attempts,
2350            "cost_usd": self.cost_usd,
2351            "mean_wall_time_ms": self.mean_wall_ms(),
2352            "item_latency_p95_ms": self.latency_p95_ms,
2353            "completion_rate": self.completion_rate(),
2354            "dead_letter_rate": self.dead_letter_rate(),
2355        })
2356    }
2357}
2358
2359#[async_trait]
2360impl CandidateEvaluator for TwinCandidateEvaluator {
2361    async fn evaluate(
2362        &self,
2363        candidate: &Candidate,
2364        request: &EvaluationRequest,
2365    ) -> Result<CandidateEvaluation> {
2366        let CandidateContent::Policy { family, parameters } = &candidate.content else {
2367            return Err(invalid(format!(
2368                "the twin-backed evaluator prices `policy` candidates; `{}` candidates \
2369                 evaluate through the application's own evaluator",
2370                candidate.kind().as_str()
2371            )));
2372        };
2373        // The candidate as a concrete policy: parsed against the family's
2374        // contract and checked against its envelope — an out-of-envelope
2375        // candidate fails here, before a single twin run.
2376        let candidate_policy = ExecutorPolicy::static_v0()
2377            .with_family_parameters(*family, parameters.clone())
2378            .map_err(|e| {
2379                invalid(format!(
2380                    "policy candidate cannot be evaluated: its parameters do not apply to \
2381                     the floor ({e}) — an out-of-envelope candidate never reaches evidence"
2382                ))
2383            })?;
2384        let version = derive_policy_version(&candidate_policy)?;
2385        let acting: Arc<dyn TwinPolicy> =
2386            Arc::new(ParameterizedPolicy::new(candidate_policy, version.clone())?);
2387
2388        let mut floor_aggregate = ArmAggregate::default();
2389        let mut candidate_aggregate = ArmAggregate::default();
2390        let mut fixture_ids = Vec::with_capacity(request.replay_evidence.len());
2391        let mut matched = 0usize;
2392        let mut divergences = Vec::new();
2393        let mut floor_runs = Vec::new();
2394        let mut candidate_runs = Vec::new();
2395        let mut completion_breached = false;
2396
2397        for fixture in &request.replay_evidence {
2398            fixture_ids.push(fixture.run_id.clone());
2399            let outcome = (|| -> Result<_> {
2400                let twin = Twin::from_snapshot(fixture.clone())?;
2401                let config = TwinRunConfig::new(self.seed)
2402                    .with_faults(self.faults.clone())
2403                    .with_workers(self.workers.clone())
2404                    .with_max_attempts(self.max_attempts);
2405                let floor_run = twin.run(&config)?;
2406                let candidate_run = twin.run(&config.with_acting(acting.clone()))?;
2407                Ok((floor_run, candidate_run))
2408            })();
2409            match outcome {
2410                Ok((floor_run, candidate_run)) => {
2411                    matched += 1;
2412                    // Per-fixture non-inferiority: a candidate that
2413                    // completes less of one fixture's work than the floor
2414                    // is a regression the aggregate must not average away.
2415                    let floor_rate =
2416                        floor_run.metrics.completed as f64 / floor_run.metrics.items.max(1) as f64;
2417                    let candidate_rate = candidate_run.metrics.completed as f64
2418                        / candidate_run.metrics.items.max(1) as f64;
2419                    if candidate_rate < floor_rate - self.completion_tolerance {
2420                        completion_breached = true;
2421                    }
2422                    floor_aggregate.fold(&floor_run.metrics);
2423                    candidate_aggregate.fold(&candidate_run.metrics);
2424                    floor_runs.push(serde_json::json!({
2425                        "fixture": fixture.run_id,
2426                        "metrics": floor_run.metrics,
2427                        "report": floor_run.report,
2428                    }));
2429                    candidate_runs.push(serde_json::json!({
2430                        "fixture": fixture.run_id,
2431                        "metrics": candidate_run.metrics,
2432                        "report": candidate_run.report,
2433                    }));
2434                }
2435                Err(error) => {
2436                    // A fixture the twin cannot re-execute is evidence the
2437                    // evaluation could not verify — a divergence, fail
2438                    // closed, the same rule the wave-4 evaluator applies.
2439                    divergences.push(ReplayDivergence {
2440                        fixture_id: fixture.run_id.clone(),
2441                        detail: error.to_string(),
2442                    });
2443                }
2444            }
2445        }
2446        fixture_ids.sort();
2447        divergences.sort_by(|a, b| a.fixture_id.cmp(&b.fixture_id));
2448
2449        let regressed = completion_breached
2450            || candidate_aggregate.completion_rate()
2451                < floor_aggregate.completion_rate() - self.completion_tolerance;
2452        let (baseline, candidate_value, delta) = match request.target_metric.as_str() {
2453            "completion_rate" => (
2454                Some(floor_aggregate.completion_rate()),
2455                Some(candidate_aggregate.completion_rate()),
2456                Some(candidate_aggregate.completion_rate() - floor_aggregate.completion_rate()),
2457            ),
2458            "cost_usd" => (
2459                Some(floor_aggregate.cost_usd),
2460                Some(candidate_aggregate.cost_usd),
2461                Some(floor_aggregate.cost_usd - candidate_aggregate.cost_usd),
2462            ),
2463            "wall_time_ms" => (
2464                Some(floor_aggregate.mean_wall_ms()),
2465                Some(candidate_aggregate.mean_wall_ms()),
2466                Some(floor_aggregate.mean_wall_ms() - candidate_aggregate.mean_wall_ms()),
2467            ),
2468            "item_latency_p95_ms" => (
2469                Some(floor_aggregate.latency_p95_ms as f64),
2470                Some(candidate_aggregate.latency_p95_ms as f64),
2471                Some(
2472                    floor_aggregate.latency_p95_ms as f64
2473                        - candidate_aggregate.latency_p95_ms as f64,
2474                ),
2475            ),
2476            // A metric the twin does not price: no values, no delta — an
2477            // improvement bar cannot clear on a metric the evidence does
2478            // not name (the gate's own rule).
2479            _ => (None, None, None),
2480        };
2481
2482        Ok(CandidateEvaluation {
2483            candidate_id: candidate.candidate_id.clone(),
2484            dataset_version: request.dataset_version.clone(),
2485            replay: ReplaySummary {
2486                fixture_ids,
2487                matched,
2488                divergences,
2489            },
2490            baseline_report: serde_json::json!({
2491                "arm": PolicyVersion::STATIC_V0,
2492                "aggregate": floor_aggregate.as_value(),
2493                "runs": floor_runs,
2494            }),
2495            candidate_report: serde_json::json!({
2496                "arm": version,
2497                "aggregate": candidate_aggregate.as_value(),
2498                "runs": candidate_runs,
2499            }),
2500            verdict: EvaluationVerdict {
2501                regressed,
2502                target_metric: request.target_metric.clone(),
2503                baseline,
2504                candidate: candidate_value,
2505                delta,
2506            },
2507            thresholds: request.thresholds,
2508            evaluated_by: self.evaluated_by.clone(),
2509            evaluated_at: Utc::now(),
2510        })
2511    }
2512}
2513
2514/// The promotion-time baseline drift is measured against: the metrics the
2515/// promoted version's own evaluation recorded for the arm it displaced
2516/// (the floor's recorded baseline — "is the promoted version regressing
2517/// against the evidence that promoted it", nothing deeper).
2518#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
2519pub struct DriftBaseline {
2520    /// Baseline completion rate, in `[0, 1]`.
2521    pub completion_rate: f64,
2522
2523    /// Baseline dead-letter rate, in `[0, 1]`.
2524    pub dead_letter_rate: f64,
2525
2526    /// Baseline p95 decision latency (the journaled
2527    /// `dependency_latency_ms` feature), when the evidence carried one.
2528    #[serde(default, skip_serializing_if = "Option::is_none")]
2529    pub latency_p95_ms: Option<u64>,
2530}
2531
2532impl DriftBaseline {
2533    /// Read the baseline out of a serialized twin evaluation report — the
2534    /// `aggregate` section [`TwinCandidateEvaluator`] writes. `None` when
2535    /// the report names no such section (a non-twin evaluation, a
2536    /// hand-authored report): drift detection requires the promotion-time
2537    /// evidence, and it fails absent rather than guessing a baseline.
2538    pub fn from_twin_report(report: &Value) -> Option<Self> {
2539        let aggregate = report.get("aggregate")?;
2540        Some(Self {
2541            completion_rate: aggregate.get("completion_rate")?.as_f64()?,
2542            dead_letter_rate: aggregate.get("dead_letter_rate")?.as_f64()?,
2543            latency_p95_ms: aggregate.get("item_latency_p95_ms").and_then(Value::as_u64),
2544        })
2545    }
2546}
2547
2548/// The declared thresholds a drift check applies. All comparisons are
2549/// against the promotion-time baseline, on the acting version's journaled
2550/// outcomes only — shadow decisions are evidence for the *next* candidate,
2551/// never for the acting version's health.
2552#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
2553pub struct DriftThresholds {
2554    /// Completion-rate drop from baseline that declares drift.
2555    pub max_completion_drop: f64,
2556
2557    /// Dead-letter-rate growth from baseline that declares drift.
2558    pub max_dead_letter_growth: f64,
2559
2560    /// p95 latency ratio `current / baseline` that declares drift (applied
2561    /// only when both sides carry the latency feature).
2562    pub max_latency_p95_ratio: f64,
2563
2564    /// Minimum terminal decisions before any verdict. Sparse evidence
2565    /// declares nothing — a drift verdict on three outcomes is noise
2566    /// wearing a label.
2567    pub min_decisions: usize,
2568}
2569
2570impl Default for DriftThresholds {
2571    fn default() -> Self {
2572        Self {
2573            max_completion_drop: 0.05,
2574            max_dead_letter_growth: 0.02,
2575            max_latency_p95_ratio: 1.25,
2576            min_decisions: 8,
2577        }
2578    }
2579}
2580
2581/// The drift check's verdict: the acting version's journaled outcomes
2582/// against its promotion-time baseline, with the reasons drift was (or
2583/// was not) declared. Carried as data — the report is the revert's
2584/// attributable cause.
2585#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
2586pub struct PolicyDriftReport {
2587    /// The version checked.
2588    pub version: PolicyVersion,
2589
2590    /// Acting decisions examined (shadow decisions excluded).
2591    pub decisions: usize,
2592
2593    /// Terminal decisions (outcomes recorded) the rates were computed
2594    /// over.
2595    pub terminal: usize,
2596
2597    /// The acting version's journaled completion rate.
2598    pub completion_rate: f64,
2599
2600    /// The acting version's journaled dead-letter rate.
2601    pub dead_letter_rate: f64,
2602
2603    /// The acting version's p95 decision latency, when carried.
2604    #[serde(default, skip_serializing_if = "Option::is_none")]
2605    pub latency_p95_ms: Option<u64>,
2606
2607    /// The baseline the check ran against.
2608    pub baseline: DriftBaseline,
2609
2610    /// Whether drift was declared.
2611    pub drifted: bool,
2612
2613    /// Why — one entry per breached threshold, or the reason nothing was
2614    /// declared (including insufficient evidence).
2615    pub reasons: Vec<String>,
2616}
2617
2618/// Detect drift on the acting policy's journaled outcomes (R0.10 wave 3).
2619///
2620/// Reads `decisions` for those made by `version` in an acting role
2621/// (`role` unset — every pre-twin decision — or
2622/// [`crate::record::DecisionRole::Acting`]); shadow decisions are
2623/// off-policy evidence, not the acting version's health. The signals are
2624/// the design's own: completion-rate drop, dead-letter growth, p95
2625/// latency ratio — declared thresholds on journaled metrics, honest about
2626/// answering "is the promoted version regressing against the evidence
2627/// that promoted it", nothing deeper. Pure: the revert that a drifted
2628/// verdict motivates is the caller's one activation of `static-v0`.
2629pub fn detect_policy_drift(
2630    decisions: &[DecisionEvent],
2631    version: &PolicyVersion,
2632    baseline: &DriftBaseline,
2633    thresholds: &DriftThresholds,
2634) -> PolicyDriftReport {
2635    let acting: Vec<&DecisionEvent> = decisions
2636        .iter()
2637        .filter(|event| {
2638            &event.policy_version == version
2639                && event.role != Some(crate::record::DecisionRole::Shadow)
2640        })
2641        .collect();
2642    let terminal: Vec<&DecisionEvent> = acting
2643        .iter()
2644        .filter(|event| {
2645            matches!(
2646                event.outcome,
2647                Some(DecisionOutcome::Success) | Some(DecisionOutcome::Failure)
2648            )
2649        })
2650        .copied()
2651        .collect();
2652    let successes = terminal
2653        .iter()
2654        .filter(|event| event.outcome == Some(DecisionOutcome::Success))
2655        .count();
2656    // Dead-lettered, as the retry family journals it: the Abort decision
2657    // with the attempt budget spent while the gates were open. The legal
2658    // set has already collapsed to `[Abort]` at that point, so the budget
2659    // and the gates are read back from the journaled features — the same
2660    // vocabulary `retry_decision_event` and the twin both pin.
2661    let dead_letters = terminal
2662        .iter()
2663        .filter(|event| {
2664            if event.outcome != Some(DecisionOutcome::Failure)
2665                || event.selected != DecisionAction::Abort
2666            {
2667                return false;
2668            }
2669            let budget_spent = match (
2670                event.features.get("attempt").and_then(Value::as_u64),
2671                event.features.get("max_attempts").and_then(Value::as_u64),
2672            ) {
2673                (Some(attempt), Some(max_attempts)) => attempt >= max_attempts,
2674                _ => false,
2675            };
2676            let effect_open = event
2677                .features
2678                .get("effect")
2679                .and_then(|value| serde_json::from_value::<Effect>(value.clone()).ok())
2680                .is_some_and(|effect| effect.is_freely_repeatable());
2681            let class_open = event
2682                .features
2683                .get("failure_class")
2684                .and_then(|value| serde_json::from_value::<ErrorClass>(value.clone()).ok())
2685                .is_some_and(|class| class.is_retryable());
2686            budget_spent && effect_open && class_open
2687        })
2688        .count();
2689    let latencies: Vec<u64> = acting
2690        .iter()
2691        .filter_map(|event| {
2692            event
2693                .features
2694                .get("dependency_latency_ms")
2695                .and_then(Value::as_u64)
2696        })
2697        .collect();
2698    let completion_rate = if terminal.is_empty() {
2699        0.0
2700    } else {
2701        successes as f64 / terminal.len() as f64
2702    };
2703    let dead_letter_rate = if terminal.is_empty() {
2704        0.0
2705    } else {
2706        dead_letters as f64 / terminal.len() as f64
2707    };
2708    let latency_p95_ms = (!latencies.is_empty()).then(|| percentile(&latencies, 95.0));
2709
2710    let mut reasons = Vec::new();
2711    let sufficient = terminal.len() >= thresholds.min_decisions;
2712    let mut drifted = false;
2713    if !sufficient {
2714        reasons.push(format!(
2715            "insufficient evidence: {} terminal decisions, fewer than the declared minimum {}",
2716            terminal.len(),
2717            thresholds.min_decisions
2718        ));
2719    } else {
2720        let completion_drop = baseline.completion_rate - completion_rate;
2721        if completion_drop > thresholds.max_completion_drop {
2722            drifted = true;
2723            reasons.push(format!(
2724                "completion rate {completion_rate:.3} is {completion_drop:.3} below the \
2725                 promotion-time baseline {:.3} (threshold {:.3})",
2726                baseline.completion_rate, thresholds.max_completion_drop
2727            ));
2728        }
2729        let dead_letter_growth = dead_letter_rate - baseline.dead_letter_rate;
2730        if dead_letter_growth > thresholds.max_dead_letter_growth {
2731            drifted = true;
2732            reasons.push(format!(
2733                "dead-letter rate {dead_letter_rate:.3} grew {dead_letter_growth:.3} over the \
2734                 promotion-time baseline {:.3} (threshold {:.3})",
2735                baseline.dead_letter_rate, thresholds.max_dead_letter_growth
2736            ));
2737        }
2738        if let (Some(current), Some(base)) = (latency_p95_ms, baseline.latency_p95_ms) {
2739            if base > 0 && current as f64 / base as f64 > thresholds.max_latency_p95_ratio {
2740                drifted = true;
2741                reasons.push(format!(
2742                    "p95 decision latency {current} ms is {:.2}x the promotion-time baseline \
2743                     {base} ms (threshold {:.2}x)",
2744                    current as f64 / base as f64,
2745                    thresholds.max_latency_p95_ratio
2746                ));
2747            }
2748        }
2749    }
2750
2751    PolicyDriftReport {
2752        version: version.clone(),
2753        decisions: acting.len(),
2754        terminal: terminal.len(),
2755        completion_rate,
2756        dead_letter_rate,
2757        latency_p95_ms,
2758        baseline: *baseline,
2759        drifted,
2760        reasons,
2761    }
2762}
2763
2764#[cfg(test)]
2765mod tests {
2766    use super::*;
2767    use crate::memory::{InMemoryMemoryStore, MemoryKind, MemoryProvenance, ValidityWindow};
2768    use serde_json::json;
2769
2770    fn ts(millis: i64) -> DateTime<Utc> {
2771        DateTime::<Utc>::from_timestamp_millis(millis).unwrap()
2772    }
2773
2774    fn distiller() -> ProvenanceAuthor {
2775        ProvenanceAuthor::Distiller {
2776            name: "correction-loop".into(),
2777        }
2778    }
2779
2780    fn memory_record(content: Value) -> MemoryRecord {
2781        MemoryRecord::new(
2782            MemoryKind::Fact,
2783            ScopeAddress::new(MemoryScope::Agent, "support-1"),
2784            MemoryProvenance {
2785                author: ProvenanceAuthor::Human {
2786                    human_id: "amjad".into(),
2787                },
2788                evidence: Default::default(),
2789                written_at: ts(1_000),
2790            },
2791            1.0,
2792            ValidityWindow::starting(ts(500)),
2793            ts(1_000),
2794            content,
2795        )
2796        .unwrap()
2797    }
2798
2799    fn memory_set_candidate(content: Value) -> Candidate {
2800        Candidate::new(
2801            CandidateContent::MemorySet {
2802                scope: ScopeAddress::new(MemoryScope::Agent, "support-1"),
2803                adds: vec![memory_record(content)],
2804                supersedes: Vec::new(),
2805            },
2806            distiller(),
2807            EvidenceSpan {
2808                run_ids: vec!["run-1".into()],
2809                ..EvidenceSpan::default()
2810            },
2811            ts(2_000),
2812        )
2813        .unwrap()
2814    }
2815
2816    fn clean_evaluation(candidate: &Candidate, delta: f64) -> CandidateEvaluation {
2817        CandidateEvaluation {
2818            candidate_id: candidate.candidate_id.clone(),
2819            dataset_version: "v3".into(),
2820            replay: ReplaySummary {
2821                fixture_ids: vec!["run-1".into()],
2822                matched: 1,
2823                divergences: Vec::new(),
2824            },
2825            baseline_report: json!({"name": "support@v3", "summary": {"run_pass_rate": 0.5}}),
2826            candidate_report: json!({"name": "support@v3", "summary": {"run_pass_rate": 0.9}}),
2827            verdict: EvaluationVerdict {
2828                regressed: false,
2829                target_metric: "run_pass_rate".into(),
2830                baseline: Some(0.5),
2831                candidate: Some(0.5 + delta),
2832                delta: Some(delta),
2833            },
2834            thresholds: EvaluationThresholds::default(),
2835            evaluated_by: distiller(),
2836            evaluated_at: ts(3_000),
2837        }
2838    }
2839
2840    #[test]
2841    fn candidate_id_is_a_content_address() {
2842        let a = memory_set_candidate(json!({"tone": "warm"}));
2843        let b = memory_set_candidate(json!({"tone": "warm"}));
2844        let c = memory_set_candidate(json!({"tone": "cold"}));
2845        // Same change converges — even across distillers and instants…
2846        assert_eq!(a.candidate_id, b.candidate_id);
2847        let d = Candidate::new(
2848            a.content.clone(),
2849            ProvenanceAuthor::System,
2850            EvidenceSpan::default(),
2851            ts(9_999),
2852        )
2853        .unwrap();
2854        assert_eq!(a.candidate_id, d.candidate_id);
2855        // …changed content is a new id.
2856        assert_ne!(a.candidate_id, c.candidate_id);
2857        assert_eq!(a.candidate_id.as_str().len(), 64);
2858    }
2859
2860    #[test]
2861    fn tampered_candidate_fails_its_own_address() {
2862        let mut candidate = memory_set_candidate(json!({"tone": "warm"}));
2863        candidate.verify_address().unwrap();
2864        candidate.candidate_id = CandidateId("f".repeat(64));
2865        assert!(matches!(
2866            candidate.verify_address(),
2867            Err(LearnError::AddressMismatch { .. })
2868        ));
2869    }
2870
2871    #[test]
2872    fn surfaces_are_the_documented_keys() {
2873        let memory = memory_set_candidate(json!({}));
2874        assert_eq!(memory.surface().as_str(), "memory:agent:support-1");
2875        let prompt = Candidate::new(
2876            CandidateContent::Prompt {
2877                name: "system".into(),
2878                prompt: "You are careful.".into(),
2879            },
2880            distiller(),
2881            EvidenceSpan::default(),
2882            ts(2_000),
2883        )
2884        .unwrap();
2885        assert_eq!(prompt.surface().as_str(), "prompt:system");
2886        let policy = Candidate::new(
2887            CandidateContent::Policy {
2888                family: DecisionFamily::Retry,
2889                parameters: json!({"max_attempts": 4}),
2890            },
2891            distiller(),
2892            EvidenceSpan::default(),
2893            ts(2_000),
2894        )
2895        .unwrap();
2896        assert_eq!(policy.surface().as_str(), "policy:retry");
2897        let tool = Candidate::new(
2898            CandidateContent::ToolPermission {
2899                tool: "shell".into(),
2900                direction: GrantDirection::Narrow,
2901            },
2902            distiller(),
2903            EvidenceSpan::default(),
2904            ts(2_000),
2905        )
2906        .unwrap();
2907        assert_eq!(tool.surface().as_str(), "tool:shell");
2908    }
2909
2910    #[test]
2911    fn lifecycle_refuses_illegal_transitions() {
2912        let candidate = memory_set_candidate(json!({}));
2913        let mut record = CandidateRecord::new(candidate.clone());
2914        // Promote before evaluate: refused, typed.
2915        let receipt = PromotionReceipt {
2916            candidate_id: candidate.candidate_id.clone(),
2917            surface: candidate.surface(),
2918            previous: None,
2919            decision: PromotionDecision {
2920                authority: PromotionAuthority::Envelope {
2921                    envelope_version: "r0.8-default".into(),
2922                },
2923                canary: None,
2924            },
2925            promoted_at: ts(4_000),
2926        };
2927        assert!(matches!(
2928            record.apply_promotion(receipt.clone()),
2929            Err(LearnError::InvalidTransition {
2930                from: CandidateStatus::Created,
2931                action: "promote",
2932            })
2933        ));
2934        // Evaluate, then promote, then refuse re-evaluation and allow rollback.
2935        record
2936            .apply_evaluation(clean_evaluation(&candidate, 0.4))
2937            .unwrap();
2938        record.apply_promotion(receipt).unwrap();
2939        assert!(matches!(
2940            record.apply_evaluation(clean_evaluation(&candidate, 0.5)),
2941            Err(LearnError::InvalidTransition {
2942                from: CandidateStatus::Promoted,
2943                action: "evaluate",
2944            })
2945        ));
2946        record
2947            .apply_rollback(RollbackReceipt {
2948                surface: candidate.surface(),
2949                from: candidate.candidate_id.clone(),
2950                to: None,
2951                cause: "operator: drift on run-9".into(),
2952                rolled_back_at: ts(5_000),
2953            })
2954            .unwrap();
2955        assert_eq!(record.status, CandidateStatus::RolledBack);
2956    }
2957
2958    #[test]
2959    fn gate_admits_in_envelope_and_refuses_out_of_it() {
2960        let envelope = PromotionEnvelope::r08_default();
2961        let candidate = memory_set_candidate(json!({"tone": "warm"}));
2962        let evaluation = clean_evaluation(&candidate, 0.4);
2963        // In-envelope: memory_set at agent scope, clean verdict → the
2964        // envelope version is the standing approval.
2965        let decision = admit_promotion(&envelope, &candidate, Some(&evaluation), None).unwrap();
2966        assert_eq!(
2967            decision.authority,
2968            PromotionAuthority::Envelope {
2969                envelope_version: "r0.8-default".into()
2970            }
2971        );
2972        // Out-of-envelope: prompt candidates always need a token in R0.8.
2973        let prompt = Candidate::new(
2974            CandidateContent::Prompt {
2975                name: "system".into(),
2976                prompt: "You are careful.".into(),
2977            },
2978            distiller(),
2979            EvidenceSpan::default(),
2980            ts(2_000),
2981        )
2982        .unwrap();
2983        let prompt_eval = clean_evaluation(&prompt, 0.4);
2984        let refused = admit_promotion(&envelope, &prompt, Some(&prompt_eval), None).unwrap_err();
2985        let effect_id = promotion_effect_id(&prompt);
2986        assert_eq!(
2987            refused,
2988            LearnError::Refused(PromotionRefusal::RequiresApproval {
2989                effect_id: effect_id.clone()
2990            })
2991        );
2992        // A token for another candidate's promotion does not transfer…
2993        let wrong = ApprovalToken::approve(promotion_effect_id(&candidate), "ops:amjad");
2994        assert!(matches!(
2995            admit_promotion(&envelope, &prompt, Some(&prompt_eval), Some(&wrong)),
2996            Err(LearnError::Refused(
2997                PromotionRefusal::ApprovalMismatch { .. }
2998            ))
2999        ));
3000        // …the correctly scoped token admits, with attribution.
3001        let token = ApprovalToken::approve(effect_id, "ops:amjad");
3002        let decision =
3003            admit_promotion(&envelope, &prompt, Some(&prompt_eval), Some(&token)).unwrap();
3004        assert_eq!(
3005            decision.authority,
3006            PromotionAuthority::Approval {
3007                approved_by: "ops:amjad".into()
3008            }
3009        );
3010    }
3011
3012    #[test]
3013    fn gate_enforces_the_evidence_bar() {
3014        let envelope = PromotionEnvelope::r08_default();
3015        let candidate = memory_set_candidate(json!({}));
3016        // Parity is not improvement.
3017        let parity = clean_evaluation(&candidate, 0.0);
3018        assert_eq!(
3019            admit_promotion(&envelope, &candidate, Some(&parity), None).unwrap_err(),
3020            LearnError::Refused(PromotionRefusal::InsufficientImprovement {
3021                delta: Some(0.0),
3022                required: 0.0,
3023            })
3024        );
3025        // Regression refuses even with improvement on the target metric.
3026        let mut regressed = clean_evaluation(&candidate, 0.4);
3027        regressed.verdict.regressed = true;
3028        assert!(matches!(
3029            admit_promotion(&envelope, &candidate, Some(&regressed), None),
3030            Err(LearnError::Refused(
3031                PromotionRefusal::EvaluationRegressed { .. }
3032            ))
3033        ));
3034        // Divergent replay refuses.
3035        let mut diverged = clean_evaluation(&candidate, 0.4);
3036        diverged.replay.divergences = vec![ReplayDivergence {
3037            fixture_id: "run-1".into(),
3038            detail: "seq 4: request hash mismatch".into(),
3039        }];
3040        assert!(matches!(
3041            admit_promotion(&envelope, &candidate, Some(&diverged), None),
3042            Err(LearnError::Refused(PromotionRefusal::ReplayDiverged { .. }))
3043        ));
3044        // A wider scope than the R0.8 default refuses.
3045        let tenant_scoped = Candidate::new(
3046            CandidateContent::MemorySet {
3047                scope: ScopeAddress::new(MemoryScope::Tenant, "default"),
3048                adds: vec![],
3049                supersedes: vec![],
3050            },
3051            distiller(),
3052            EvidenceSpan::default(),
3053            ts(2_000),
3054        )
3055        .unwrap();
3056        let evaluation = clean_evaluation(&tenant_scoped, 0.4);
3057        assert!(matches!(
3058            admit_promotion(&envelope, &tenant_scoped, Some(&evaluation), None),
3059            Err(LearnError::Refused(
3060                PromotionRefusal::ScopeNotAutoPromotable {
3061                    scope: MemoryScope::Tenant
3062                }
3063            ))
3064        ));
3065        // No evaluation at all refuses, even for an in-envelope kind.
3066        assert!(matches!(
3067            admit_promotion(&envelope, &candidate, None, None),
3068            Err(LearnError::Refused(PromotionRefusal::NotEvaluated { .. }))
3069        ));
3070    }
3071
3072    #[test]
3073    fn canary_draw_is_deterministic_uniform_and_scoped() {
3074        let candidate = memory_set_candidate(json!({}));
3075        let surface = candidate.surface();
3076        let binding = CanaryBinding {
3077            candidate_id: candidate.candidate_id.clone(),
3078            fraction: 0.25,
3079        };
3080        // Deterministic per (surface, candidate, run).
3081        assert_eq!(
3082            canary_admits(&binding, &surface, "run-7"),
3083            canary_admits(&binding, &surface, "run-7")
3084        );
3085        // Full fraction admits everything.
3086        let full = CanaryBinding {
3087            candidate_id: candidate.candidate_id.clone(),
3088            fraction: 1.0,
3089        };
3090        for run in 0..32 {
3091            assert!(canary_admits(&full, &surface, &format!("run-{run}")));
3092        }
3093        // A quarter fraction admits roughly a quarter of traffic (loose
3094        // bounds: the draw is uniform over the digest space).
3095        let admitted = (0..1_000)
3096            .filter(|run| canary_admits(&binding, &surface, &format!("run-{run}")))
3097            .count();
3098        assert!(
3099            (150..=350).contains(&admitted),
3100            "fraction 0.25 admitted {admitted}/1000 runs"
3101        );
3102    }
3103
3104    #[test]
3105    fn pointer_moves_on_promotion_and_reponts_on_rollback() {
3106        let a = memory_set_candidate(json!({"v": "a"}));
3107        let b = memory_set_candidate(json!({"v": "b"}));
3108        let pointer = VersionPointer::new(a.surface());
3109        assert_eq!(pointer.active, None);
3110
3111        let promote_a = PromotionReceipt {
3112            candidate_id: a.candidate_id.clone(),
3113            surface: a.surface(),
3114            previous: None,
3115            decision: PromotionDecision {
3116                authority: PromotionAuthority::Envelope {
3117                    envelope_version: "r0.8-default".into(),
3118                },
3119                canary: None,
3120            },
3121            promoted_at: ts(4_000),
3122        };
3123        let pointer = pointer.promoted(&promote_a);
3124        assert_eq!(pointer.active, Some(a.candidate_id.clone()));
3125
3126        let promote_b = PromotionReceipt {
3127            candidate_id: b.candidate_id.clone(),
3128            surface: a.surface(),
3129            previous: Some(a.candidate_id.clone()),
3130            decision: promote_a.decision.clone(),
3131            promoted_at: ts(5_000),
3132        };
3133        let pointer = pointer.promoted(&promote_b);
3134        assert_eq!(pointer.active, Some(b.candidate_id.clone()));
3135
3136        // Rollback re-points to the previous candidate — byte-exact,
3137        // because the candidate id IS the content.
3138        let pointer = pointer.rolled_back(&RollbackReceipt {
3139            surface: a.surface(),
3140            from: b.candidate_id.clone(),
3141            to: promote_b.previous.clone(),
3142            cause: "drift".into(),
3143            rolled_back_at: ts(6_000),
3144        });
3145        assert_eq!(pointer.active, Some(a.candidate_id.clone()));
3146    }
3147
3148    #[tokio::test]
3149    async fn overlay_applies_the_candidate_as_a_read_lens() {
3150        let base = Arc::new(InMemoryMemoryStore::new());
3151        let existing = memory_record(json!({"tone": "flat"}));
3152        base.put(&existing).await.unwrap();
3153
3154        let mut added = memory_record(json!({"tone": "warm"}));
3155        added.supersedes = Some(existing.memory_id.clone());
3156        let candidate = Candidate::new(
3157            CandidateContent::MemorySet {
3158                scope: ScopeAddress::new(MemoryScope::Agent, "support-1"),
3159                adds: vec![added.clone()],
3160                supersedes: Vec::new(),
3161            },
3162            distiller(),
3163            EvidenceSpan::default(),
3164            ts(2_000),
3165        )
3166        .unwrap();
3167        let overlay = CandidateOverlay::new(base.clone(), &candidate).unwrap();
3168        // The add answers…
3169        assert_eq!(overlay.get(&added.memory_id).await.unwrap(), Some(added));
3170        // …the base record still fetches by id…
3171        assert_eq!(
3172            overlay.get(&existing.memory_id).await.unwrap(),
3173            Some(existing.clone())
3174        );
3175        // …but drops out of default retrieval via the add's supersedes
3176        // field (core's matcher, over the merged universe)…
3177        let listed = overlay
3178            .query(&MemoryQuery::default(), Utc::now())
3179            .await
3180            .unwrap();
3181        assert_eq!(listed.len(), 1);
3182        // …and writes through the lens fail.
3183        assert!(overlay.put(&existing).await.is_err());
3184    }
3185}