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(®ressed), 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}