Skip to main content

services/
local.rs

1//! `refinements.*` and `experiments.*` of `ultron/local-services.ts` (`NativeLocalServices`): versioned
2//! refinements (lessons, instruction and skill changes) with their proposal, approval, activation, rejection and
3//! rollback flow over one append-only event ledger, and the experiment history of recorded runs.
4//!
5//! Requests (Python reaches them through `refinements.*` of `memory_api.py` and `rlm.host_request`):
6//! - `refinements.propose` `{kind, target, baseVersion, content, evidence?, scope?}`
7//! - `refinements.get` / `activate` / `approve` / `reject` / `rollback` `{id}`; `current` `{kind, target}`; `list` `{}`
8//! - `experiments.record` `{run}`; `compare` `{baseline, candidate}`; `list` `{}`
9//!
10//! Guarantees the host enforces here, never the model: a target names a refinement kind and never human-owned
11//! authority (policy, grants, acceptance, approval, trusted instructions); content cannot request tools, grants,
12//! models, budgets or permissions, at proposal and again at activation; activation needs nonempty evidence, the
13//! current base version and the domain validation; approval (off by default) never overrides validation; a
14//! decided record is never re-opened. Every mutation is one appended event; reads replay the ledger, keeping only
15//! the events anchored on the caller's conversation branch (A07). Experiments are append-only, and only runs on
16//! the same frozen fixture compare. Calls serialize; a failed write makes the service unusable until reopened.
17
18use kernel_apis::artifacts::KeyedDocuments;
19use kernel_apis::store::read_versioned;
20use kernel_apis::util::{Clock, system_clock};
21use serde_json::{Map, Value, json};
22use session_journal::ns::{EXPERIMENTS, REFINEMENTS};
23use std::sync::{Arc, Mutex};
24
25const KINDS: [&str; 4] = ["observation", "instruction", "skill", "agent"];
26const PROTECTED_NAMES: [&str; 3] = ["agents.md", "security", "policy"];
27/// Name segments of human-owned authority: trusted instructions, security policy, grants, the acceptance instrument,
28/// judge thresholds and approval. Compared case- and separator-insensitively against every segment of a target.
29const PROTECTED_TOKENS: [&str; 19] = [
30    "agents",
31    "agentsmd",
32    "security",
33    "policy",
34    "policies",
35    "grant",
36    "grants",
37    "permission",
38    "permissions",
39    "capability",
40    "capabilities",
41    "acceptance",
42    "instrument",
43    "judge",
44    "threshold",
45    "thresholds",
46    "approval",
47    "approvals",
48    "sandbox",
49];
50/// Content keys that would grant tools, models, budgets or permissions if a consumer honored them.
51const CAPABILITY_KEYS: [&str; 16] = [
52    "allowedtools",
53    "tools",
54    "tool",
55    "grant",
56    "grants",
57    "permission",
58    "permissions",
59    "capability",
60    "capabilities",
61    "model",
62    "budget",
63    "timeout",
64    "policy",
65    "approval",
66    "sandbox",
67    "env",
68];
69const MALFORMED: &str = "Malformed local service fields";
70const UNCERTAIN: &str = "Document durability is uncertain; reopen the service before use";
71
72/// The domain check run on activation only: `Ok(true)` passes, `Ok(false)` refuses it as failed validation, an
73/// error refuses it with that message (TS `validate` returning true/undefined, false, or throwing).
74pub type Validator = Arc<dyn Fn(&str, &Value) -> Result<bool, String> + Send + Sync>;
75/// A fresh record id (`crypto.randomUUID()`).
76pub type Ids = Arc<dyn Fn() -> String + Send + Sync>;
77/// Whether an anchor lies on the conversation branch in use.
78pub type OnBranch = Arc<dyn Fn(&str) -> bool + Send + Sync>;
79
80/// `NativeLocalServicesOptions` for refinements and experiments.
81#[derive(Clone)]
82pub struct LocalOptions {
83    pub validate: Option<Validator>,
84    /// Opt-in control: activation requires a prior `refinements.approve`. Off by default.
85    pub require_approval: bool,
86    pub now: Clock,
87    pub ids: Ids,
88}
89
90impl Default for LocalOptions {
91    fn default() -> Self {
92        LocalOptions {
93            validate: None,
94            require_approval: false,
95            now: system_clock(),
96            ids: Arc::new(jsrt::random::uuid_v4),
97        }
98    }
99}
100
101/// The conversation branch a request is made on (`RefinementBranch`).
102#[derive(Clone, Default)]
103pub struct Branch {
104    /// The entry the change is made at; `None` for an empty conversation.
105    pub anchor: Option<String>,
106    /// Whether an anchor lies on the branch in use; `None` applies every event.
107    pub on_branch: Option<OnBranch>,
108}
109
110/// `value.toLowerCase().replace(/[-_\s]/g, "")`.
111fn normalize(value: &str) -> String {
112    value
113        .to_lowercase()
114        .chars()
115        .filter(|ch| *ch != '-' && *ch != '_' && !jsrt::string::is_space(*ch))
116        .collect()
117}
118
119/// Positions where `text` has `\r?\n---` (`/\r?\n---/` tried at each index, `\r` first).
120fn closing_fence(text: &str, from: usize, then_newline: bool) -> Option<(usize, usize)> {
121    let bytes = text.as_bytes();
122    let newline_at = |at: usize| -> Option<usize> {
123        if bytes.get(at) == Some(&b'\r') && bytes.get(at + 1) == Some(&b'\n') {
124            Some(at + 2)
125        } else if bytes.get(at) == Some(&b'\n') {
126            Some(at + 1)
127        } else {
128            None
129        }
130    };
131    (from..=text.len()).find_map(|at| {
132        let after = newline_at(at)?;
133        if !text[after..].starts_with("---") {
134            return None;
135        }
136        let end = after + 3;
137        if !then_newline {
138            return Some((at, end));
139        }
140        newline_at(end).map(|body| (at, body))
141    })
142}
143
144/// `/^---\r?\n([\s\S]*?)\r?\n---/` on `text`: the frontmatter, and where the text after the closing fence starts
145/// (past its newline when `then_newline`, as `/...\r?\n---\r?\n([\s\S]*)$/`).
146pub(crate) fn frontmatter(text: &str, then_newline: bool) -> Option<(&str, &str)> {
147    let start = if text.starts_with("---\r\n") {
148        5
149    } else if text.starts_with("---\n") {
150        4
151    } else {
152        return None;
153    };
154    let (close, rest) = closing_fence(text, start, then_newline)?;
155    Some((&text[start..close], &text[rest..]))
156}
157
158/// Capability non-escalation: a structured or frontmatter key that would claim authority.
159fn escalation(value: &Value) -> Option<String> {
160    match value {
161        Value::String(text) => {
162            let (front, _) = frontmatter(text.trim_start_matches(jsrt::string::is_space), false)?;
163            for line in front.split('\n') {
164                let line = line.strip_suffix('\r').unwrap_or(line);
165                // /^\s*([A-Za-z][\w-]*)\s*:/
166                let rest = line.trim_start_matches(jsrt::string::is_space);
167                let mut chars = rest.char_indices();
168                if !chars.next().is_some_and(|(_, ch)| ch.is_ascii_alphabetic()) {
169                    continue;
170                }
171                let end = chars
172                    .find(|(_, ch)| !(ch.is_ascii_alphanumeric() || *ch == '_' || *ch == '-'))
173                    .map_or(rest.len(), |(at, _)| at);
174                let key = &rest[..end];
175                if rest[end..].trim_start_matches(jsrt::string::is_space).starts_with(':')
176                    && CAPABILITY_KEYS.contains(&normalize(key).as_str())
177                {
178                    return Some(key.to_string());
179                }
180            }
181            None
182        }
183        Value::Array(items) => items.iter().find_map(escalation),
184        Value::Object(map) => map.iter().find_map(|(key, item)| {
185            if CAPABILITY_KEYS.contains(&normalize(key).as_str()) {
186                Some(key.clone())
187            } else {
188                escalation(item)
189            }
190        }),
191        _ => None,
192    }
193}
194
195/// `sameJson`: deep equality with object keys in any order (numbers compare as JavaScript numbers).
196fn same_json(left: &Value, right: &Value) -> bool {
197    match (left, right) {
198        (Value::Number(a), Value::Number(b)) => a.as_f64() == b.as_f64(),
199        (Value::Array(a), Value::Array(b)) => a.len() == b.len() && a.iter().zip(b).all(|(x, y)| same_json(x, y)),
200        (Value::Object(a), Value::Object(b)) => {
201            a.len() == b.len() && a.iter().all(|(key, x)| b.get(key).is_some_and(|y| same_json(x, y)))
202        }
203        _ => left == right,
204    }
205}
206
207/// `fields(value, required, optional)`: an object with every required key and no other than the optional ones.
208fn fields<'a>(value: &'a Value, required: &[&str], optional: &[&str]) -> Result<&'a Map<String, Value>, String> {
209    let map = value.as_object().ok_or(MALFORMED)?;
210    if required.iter().any(|key| !map.contains_key(*key))
211        || map
212            .keys()
213            .any(|key| !required.contains(&key.as_str()) && !optional.contains(&key.as_str()))
214    {
215        return Err(MALFORMED.into());
216    }
217    Ok(map)
218}
219
220/// `/^[a-z]+:[a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*$/`.
221fn target_shape(target: &str) -> bool {
222    let Some((namespace, name)) = target.split_once(':') else {
223        return false;
224    };
225    let word = |part: &str| {
226        !part.is_empty()
227            && part
228                .bytes()
229                .all(|b| b.is_ascii_alphanumeric() || b == b'_' || b == b'-')
230    };
231    !namespace.is_empty() && namespace.bytes().all(|b| b.is_ascii_lowercase()) && name.split('.').all(word)
232}
233
234/// `identity(kind, target)`: a known kind, and a `kind:name` target that names no protected authority.
235fn identity(kind: &Value, target: &Value) -> Result<(String, String), String> {
236    let kind = kind
237        .as_str()
238        .filter(|kind| KINDS.contains(kind))
239        .ok_or("Invalid refinement kind")?;
240    let target = target
241        .as_str()
242        .filter(|target| target_shape(target))
243        .ok_or("Target must be an explicit namespace:name ID, not a path")?;
244    let (namespace, name) = target.split_once(':').unwrap_or_default();
245    if namespace != kind
246        || PROTECTED_NAMES.contains(&name.to_lowercase().as_str())
247        || PROTECTED_TOKENS.contains(&normalize(name).as_str())
248        || name
249            .split(['.', '-', '_'])
250            .any(|segment| PROTECTED_TOKENS.contains(&normalize(segment).as_str()))
251    {
252        return Err("Forbidden refinement target".into());
253    }
254    Ok((kind.to_string(), target.to_string()))
255}
256
257fn nonempty(value: &Value) -> bool {
258    match value {
259        Value::Null => false,
260        Value::String(text) => !jsrt::string::trim(text).is_empty(),
261        Value::Array(items) => items.iter().any(nonempty),
262        Value::Object(map) => map.values().any(nonempty),
263        _ => true,
264    }
265}
266
267/// `proposal(value)`: `{kind, target, baseVersion, content, evidence, scope}` with the defaults filled in.
268fn proposal(value: &Value) -> Result<Value, String> {
269    let map = fields(
270        value,
271        &["kind", "target", "baseVersion", "content"],
272        &["evidence", "scope"],
273    )?;
274    let (kind, target) = identity(&map["kind"], &map["target"])?;
275    let base = &map["baseVersion"];
276    if !jsrt::number::safe_integer(base).is_some_and(|version| version >= 0) {
277        return Err("baseVersion must be a nonnegative safe integer".into());
278    }
279    let content = &map["content"];
280    if !(content.is_string() || content.is_object() || content.is_array()) || !nonempty(content) {
281        return Err("Content must be nonempty JSON text, an object, or an array".into());
282    }
283    let evidence = map.get("evidence").cloned().unwrap_or_else(|| json!([]));
284    if evidence.is_number() || evidence.is_boolean() {
285        return Err("Evidence must be JSON text, an object, or an array".into());
286    }
287    let scope = map.get("scope").cloned().unwrap_or_else(|| json!("session"));
288    if !scope
289        .as_str()
290        .is_some_and(|scope| !jsrt::string::trim(scope).is_empty())
291    {
292        return Err("Scope must be a nonempty string".into());
293    }
294    Ok(json!({
295        "kind": kind, "target": target, "baseVersion": base, "content": content, "evidence": evidence, "scope": scope,
296    }))
297}
298
299/// One refinement (`RefinementRecord`).
300#[derive(Clone, Debug)]
301struct Record {
302    id: String,
303    kind: String,
304    target: String,
305    base_version: Value,
306    content: Value,
307    evidence: Value,
308    scope: Value,
309    version: Option<i64>,
310    previous_id: Option<String>,
311    state: &'static str,
312    approval: Option<&'static str>,
313    history: Vec<Value>,
314}
315
316impl Record {
317    fn json(&self) -> Value {
318        json!({
319            "id": self.id, "kind": self.kind, "target": self.target, "baseVersion": self.base_version,
320            "content": self.content, "evidence": self.evidence, "scope": self.scope, "version": self.version,
321            "previousId": self.previous_id, "state": self.state, "approval": self.approval, "history": self.history,
322        })
323    }
324
325    fn transition(&mut self, state: &'static str, at: &str, cause: &str) {
326        self.state = state;
327        self.history.push(json!({"state": state, "at": at, "cause": cause}));
328    }
329}
330
331fn lookup(records: &[Record], id: &Value) -> Result<usize, String> {
332    let id = id.as_str().filter(|id| !id.is_empty()).ok_or("Invalid refinement ID")?;
333    records
334        .iter()
335        .position(|record| record.id == id)
336        .ok_or_else(|| format!("Unknown refinement: {id}"))
337}
338
339fn active(records: &[Record], kind: &str, target: &str) -> Option<usize> {
340    records
341        .iter()
342        .position(|record| record.kind == kind && record.target == target && record.state == "active")
343}
344
345fn on_branch(event: &Value, branch: Option<&Branch>) -> bool {
346    let Some(test) = branch.and_then(|branch| branch.on_branch.as_ref()) else {
347        return true;
348    };
349    match event.as_object().and_then(|event| event.get("anchor")) {
350        Some(Value::String(anchor)) => test(anchor),
351        _ => true,
352    }
353}
354
355/// `apply(records, event)`: one ledger event; returns the index of the record it changed.
356fn apply(records: &mut Vec<Record>, event: &Value) -> Result<usize, String> {
357    let map = event.as_object().ok_or("Malformed refinement event")?;
358    let action = map.get("action").and_then(Value::as_str).unwrap_or_default();
359    let optional: &[&str] = match action {
360        "propose" => &["proposal"],
361        "activate" => &["approval", "anchor"],
362        "rollback" => &["anchor"],
363        _ => &[],
364    };
365    fields(event, &["action", "id", "at"], optional)?;
366    let (Some(id), Some(at)) = (
367        map["id"].as_str().filter(|id| !id.is_empty()),
368        map["at"].as_str().filter(|at| jsrt::date::parse_date(at).is_some()),
369    ) else {
370        return Err("Malformed refinement event".into());
371    };
372    if action == "propose" {
373        let data = proposal(map.get("proposal").unwrap_or(&Value::Null))?;
374        if records.iter().any(|record| record.id == id) {
375            return Err("Duplicate refinement ID".into());
376        }
377        let text = |key: &str| data[key].as_str().unwrap_or_default().to_string();
378        let mut record = Record {
379            id: id.into(),
380            kind: text("kind"),
381            target: text("target"),
382            base_version: data["baseVersion"].clone(),
383            content: data["content"].clone(),
384            evidence: data["evidence"].clone(),
385            scope: data["scope"].clone(),
386            version: None,
387            previous_id: None,
388            state: "proposed",
389            approval: None,
390            history: Vec::new(),
391        };
392        record.transition("proposed", at, id);
393        records.push(record);
394        return Ok(records.len() - 1);
395    }
396    let index = lookup(records, &map["id"])?;
397    match action {
398        "activate" => {
399            let record = &records[index];
400            if record.state != "proposed" {
401                return Err("Only a proposed refinement can be activated".into());
402            }
403            identity(&json!(record.kind), &json!(record.target))?;
404            if !nonempty(&record.evidence) {
405                return Err("Activation requires nonempty evidence".into());
406            }
407            let previous = active(records, &record.kind, &record.target);
408            let current = previous.and_then(|p| records[p].version).unwrap_or(0);
409            if record.base_version.as_f64() != Some(current as f64) {
410                return Err("Stale base version".into());
411            }
412            let version = records
413                .iter()
414                .filter(|item| item.kind == record.kind && item.target == record.target)
415                .map(|item| item.version.unwrap_or(0))
416                .fold(0, i64::max);
417            if version + 1 > jsrt::number::MAX_SAFE_INTEGER {
418                return Err("Version exhausted".into());
419            }
420            let approval = map.get("approval");
421            if approval.is_some_and(|a| a != "approved" && a != "not_required") {
422                return Err("Malformed refinement approval".into());
423            }
424            let claims = approval.is_some_and(|a| a == "approved");
425            if claims && record.approval != Some("approved") {
426                return Err("Activation claims an approval that was not recorded".into());
427            }
428            let previous_id = previous.map(|p| records[p].id.clone());
429            let record = &mut records[index];
430            record.version = Some(version + 1);
431            record.previous_id = previous_id;
432            if record.approval != Some("approved") {
433                record.approval = approval.is_some_and(|a| a == "not_required").then_some("not_required");
434            }
435            if let Some(previous) = previous {
436                records[previous].transition("superseded", at, id);
437            }
438            records[index].transition("active", at, id);
439        }
440        "approve" => {
441            // Approval never overrides validation: activation still runs every check.
442            if records[index].state != "proposed" {
443                return Err("Only a proposed refinement can be approved".into());
444            }
445            records[index].approval = Some("approved");
446        }
447        "reject" => {
448            if records[index].state != "proposed" {
449                return Err("Only a proposed refinement can be rejected".into());
450            }
451            records[index].transition("rejected", at, id);
452        }
453        "rollback" => {
454            let record = &records[index];
455            if active(records, &record.kind, &record.target) != Some(index) {
456                return Err("Only the latest active refinement can be rolled back".into());
457            }
458            let previous = record.previous_id.clone();
459            records[index].transition("rolled_back", at, id);
460            if let Some(previous) = previous {
461                let previous = lookup(records, &json!(previous))?;
462                records[previous].transition("active", at, id);
463            }
464        }
465        _ => return Err("Unknown refinement action".into()),
466    }
467    Ok(index)
468}
469
470/// `experiment(value)`: a recorded run with valid metadata whose usage, when present, reconciles.
471fn experiment(value: &Value) -> Result<(), String> {
472    const INVALID: &str = "Experiment requires variant, fixtureHash, outcome and valid record metadata";
473    let map = value.as_object().ok_or(INVALID)?;
474    let outcome = map.get("outcome").and_then(Value::as_str);
475    if !map.get("variant").is_some_and(Value::is_string)
476        || !map.get("fixtureHash").is_some_and(Value::is_string)
477        || !outcome.is_some_and(|o| ["passed", "failed", "incomplete"].contains(&o))
478        || !map.get("id").and_then(Value::as_str).is_some_and(|id| !id.is_empty())
479        || !map
480            .get("recordedAt")
481            .and_then(Value::as_str)
482            .is_some_and(|at| jsrt::date::parse_date(at).is_some())
483    {
484        return Err(INVALID.into());
485    }
486    if let Some(usage) = map.get("usage") {
487        let usage = usage.as_object().ok_or("Experiment usage must be an object")?;
488        let mut sum = 0.0;
489        for (key, amount) in usage {
490            let amount = amount
491                .as_f64()
492                .filter(|a| a.is_finite() && *a >= 0.0)
493                .ok_or("Experiment usage amounts must be finite and nonnegative")?;
494            if key != "total" {
495                sum += amount;
496            }
497        }
498        let total = usage.get("total").and_then(Value::as_f64);
499        if !total.is_some_and(|total| (total - sum).abs() <= 1e-9 * sum.max(1.0)) {
500            return Err("Experiment usage total does not reconcile with its parts".into());
501        }
502    }
503    Ok(())
504}
505
506/// Refinements and experiments over keyed durable documents (one service instance per owner).
507pub struct LocalServices {
508    documents: Box<dyn KeyedDocuments>,
509    options: LocalOptions,
510    /// A failed write left durability unknown.
511    uncertain: Mutex<bool>,
512}
513
514impl LocalServices {
515    pub fn new(documents: Box<dyn KeyedDocuments>, options: LocalOptions) -> Self {
516        LocalServices {
517            documents,
518            options,
519            uncertain: Mutex::new(false),
520        }
521    }
522
523    /// The session worker's service (`createWorkerServices`): activation runs the worker's content checks
524    /// ([`crate::validation::validate_refinement_content`]); approval stays off.
525    pub fn worker(documents: Box<dyn KeyedDocuments>) -> Self {
526        LocalServices::new(
527            documents,
528            LocalOptions {
529                validate: Some(crate::validation::worker_validator()),
530                ..LocalOptions::default()
531            },
532        )
533    }
534
535    /// Serves one request; `branch` is the caller's conversation branch (none: every event applies).
536    pub fn handle(&self, kind: &str, payload: &Value, branch: Option<&Branch>) -> Result<Value, String> {
537        let mut uncertain = jsrt::sync::lock(&self.uncertain);
538        if *uncertain {
539            return Err(UNCERTAIN.into());
540        }
541        let persist = |key: &str, value: &Value, uncertain: &mut bool| -> Result<(), String> {
542            self.documents.set(key, value).inspect_err(|_| *uncertain = true)
543        };
544        match kind {
545            "refinements.propose"
546            | "refinements.list"
547            | "refinements.get"
548            | "refinements.current"
549            | "refinements.activate"
550            | "refinements.approve"
551            | "refinements.reject"
552            | "refinements.rollback" => self.refinements(kind, payload, branch, &mut |key, value| {
553                persist(key, value, &mut uncertain)
554            }),
555            "experiments.record" | "experiments.list" | "experiments.compare" => {
556                self.experiments(kind, payload, &mut |key, value| persist(key, value, &mut uncertain))
557            }
558            _ => Err(format!("Unknown local service request: {kind}")),
559        }
560    }
561
562    pub fn current(&self, kind: &str, target: &str, branch: Option<&Branch>) -> Result<Option<Value>, String> {
563        let value = self.handle("refinements.current", &json!({"kind": kind, "target": target}), branch)?;
564        Ok((!value.is_null()).then_some(value))
565    }
566
567    fn now(&self) -> String {
568        jsrt::date::iso_string((self.options.now)())
569    }
570
571    fn records(&self, branch: Option<&Branch>) -> Result<(Vec<Record>, Vec<Value>), String> {
572        let saved = self.documents.get(REFINEMENTS.key)?;
573        let mut records = Vec::new();
574        let mut events = Vec::new();
575        if let Some(stored) = read_versioned(&REFINEMENTS.address(), saved, REFINEMENTS.version_field)? {
576            let replay = (|| -> Result<(), String> {
577                let document = fields(&stored, &["formatVersion", "events"], &[])?;
578                let list = document["events"].as_array();
579                if document["formatVersion"].as_f64() != Some(1.0) || list.is_none() {
580                    return Err("Unsupported document format".into());
581                }
582                events = list.cloned().unwrap_or_default();
583                for event in &events {
584                    if on_branch(event, branch) {
585                        apply(&mut records, event)?;
586                    }
587                }
588                Ok(())
589            })();
590            replay.map_err(|_| "Invalid refinement document".to_string())?;
591        }
592        Ok((records, events))
593    }
594
595    fn refinements(
596        &self,
597        kind: &str,
598        payload: &Value,
599        branch: Option<&Branch>,
600        persist: &mut dyn FnMut(&str, &Value) -> Result<(), String>,
601    ) -> Result<Value, String> {
602        let (mut records, events) = self.records(branch)?;
603        if kind == "refinements.list" {
604            fields(payload, &[], &[])?;
605            return Ok(Value::Array(records.iter().map(Record::json).collect()));
606        }
607        if kind == "refinements.current" {
608            let map = fields(payload, &["kind", "target"], &[])?;
609            let (kind, target) = identity(&map["kind"], &map["target"])?;
610            return Ok(active(&records, &kind, &target).map_or(Value::Null, |index| records[index].json()));
611        }
612        let mut event = Map::new();
613        if kind == "refinements.propose" {
614            let data = proposal(payload)?;
615            if let Some(key) = escalation(&data["content"]) {
616                return Err(format!("Refinement content cannot request capabilities ({key})"));
617            }
618            // An equivalent pending or active proposal, or a rejected one resubmitted without new evidence, is a
619            // duplicate rather than a new proposal.
620            let duplicate = records.iter().find(|record| {
621                record.kind == data["kind"]
622                    && record.target == data["target"]
623                    && record.scope == data["scope"]
624                    && same_json(&record.content, &data["content"])
625                    && (record.state == "proposed"
626                        || record.state == "active"
627                        || (record.state == "rejected" && same_json(&record.evidence, &data["evidence"])))
628            });
629            if let Some(duplicate) = duplicate {
630                return Err(format!(
631                    "Duplicate refinement proposal: {} ({})",
632                    duplicate.id, duplicate.state
633                ));
634            }
635            event.insert("action".into(), "propose".into());
636            event.insert("id".into(), (self.options.ids)().into());
637            event.insert("proposal".into(), data);
638            event.insert("at".into(), self.now().into());
639        } else {
640            let map = fields(payload, &["id"], &[])?;
641            if kind == "refinements.get" {
642                return Ok(records[lookup(&records, &map["id"])?].json());
643            }
644            let action = &kind["refinements.".len()..];
645            event.insert("action".into(), action.into());
646            event.insert("id".into(), map["id"].clone());
647            event.insert("at".into(), self.now().into());
648            if (action == "activate" || action == "rollback")
649                && let Some(anchor) = branch.and_then(|branch| branch.anchor.clone())
650            {
651                event.insert("anchor".into(), anchor.into());
652            }
653            if action == "activate" {
654                let pending = &records[lookup(&records, &map["id"])?];
655                if let Some(key) = escalation(&pending.content) {
656                    return Err(format!("Refinement content cannot request capabilities ({key})"));
657                }
658                if self.options.require_approval && pending.approval != Some("approved") {
659                    return Err("Activation requires approval".into());
660                }
661                let approval = if pending.approval == Some("approved") {
662                    "approved"
663                } else {
664                    "not_required"
665                };
666                event.insert("approval".into(), approval.into());
667            }
668        }
669        let event = Value::Object(event);
670        let index = apply(&mut records, &event)?;
671        let result = &records[index];
672        if event["action"] == "activate"
673            && let Some(validate) = &self.options.validate
674            && !validate(&result.kind, &result.content)?
675        {
676            return Err("Refinement content validation failed".into());
677        }
678        let mut next = events;
679        next.push(event);
680        persist(REFINEMENTS.key, &json!({"formatVersion": 1, "events": next}))?;
681        Ok(result.json())
682    }
683
684    fn experiments(
685        &self,
686        kind: &str,
687        payload: &Value,
688        persist: &mut dyn FnMut(&str, &Value) -> Result<(), String>,
689    ) -> Result<Value, String> {
690        let saved = self.documents.get(EXPERIMENTS.key)?;
691        let mut runs: Vec<Value> = Vec::new();
692        if let Some(stored) = read_versioned(&EXPERIMENTS.address(), saved, EXPERIMENTS.version_field)? {
693            let document = fields(&stored, &["formatVersion", "runs"], &[])?;
694            let list = document["runs"].as_array();
695            if document["formatVersion"].as_f64() != Some(1.0) || list.is_none() {
696                return Err("Invalid experiment document".into());
697            }
698            let mut seen = std::collections::HashSet::new();
699            for run in list.into_iter().flatten() {
700                experiment(run)?;
701                if !seen.insert(run["id"].as_str().unwrap_or_default().to_string()) {
702                    return Err("Duplicate experiment ID".into());
703                }
704                runs.push(run.clone());
705            }
706        }
707        match kind {
708            "experiments.list" => {
709                fields(payload, &[], &[])?;
710                Ok(Value::Array(runs))
711            }
712            "experiments.record" => {
713                let map = fields(payload, &["run"], &[])?;
714                let mut value = map["run"].as_object().cloned().ok_or("Invalid experiment run")?;
715                value.insert("id".into(), (self.options.ids)().into());
716                value.insert("recordedAt".into(), self.now().into());
717                let value = Value::Object(value);
718                experiment(&value)?;
719                runs.push(value.clone());
720                persist(EXPERIMENTS.key, &json!({"formatVersion": 1, "runs": runs}))?;
721                Ok(value)
722            }
723            _ => {
724                let map = fields(payload, &["baseline", "candidate"], &[])?;
725                let find = |id: &Value| runs.iter().find(|run| run["id"] == *id);
726                let (Some(baseline), Some(candidate)) = (find(&map["baseline"]), find(&map["candidate"])) else {
727                    return Err("Unknown experiment".into());
728                };
729                if baseline["fixtureHash"] != candidate["fixtureHash"] {
730                    return Err("Different fixtures cannot form a matched comparison".into());
731                }
732                Ok(json!({
733                    "baseline": baseline, "candidate": candidate,
734                    "claim": "Observed runs only; no statistical superiority established",
735                }))
736            }
737        }
738    }
739}
740
741/// The conversation branch refinements follow (`mainBranch`): the main lane's tip and which anchors are on its
742/// path, read when a request is made.
743pub type BranchSource = Arc<dyn Fn() -> Branch + Send + Sync>;
744
745/// An active refinement record as prompts show it: `{id, version, text}`, text content as is, other content as its
746/// JSON.
747pub fn refinement_view(record: &Value) -> Value {
748    let text = match &record["content"] {
749        Value::String(text) => text.clone(),
750        other => jsrt::json::stringify(other),
751    };
752    json!({"id": record["id"], "version": record["version"], "text": text})
753}
754
755/// A definition id's active instruction refinements, `[{id, version, text}]`.
756pub type InstructionHook = Arc<dyn Fn(&str) -> Result<Vec<Value>, String> + Send + Sync>;
757
758/// The active instruction refinements of a definition id as a typed-agent host's refinement hook
759/// (`refinements` of `NativeHostOptions`): `[{id, version, text}]` of `instruction:<definition id>` on the branch
760/// `branch` names (`mainBranch`; every event without one).
761pub fn instruction_hook(services: Arc<LocalServices>, branch: Option<BranchSource>) -> InstructionHook {
762    Arc::new(move |definition: &str| {
763        let branch = branch.as_ref().map(|source| source());
764        let current = services.current("instruction", &format!("instruction:{definition}"), branch.as_ref())?;
765        Ok(current.map(|record| vec![refinement_view(&record)]).unwrap_or_default())
766    })
767}
768
769/// `refinements.*` and `experiments.*` as a host module. With a `branch`, refinements follow the conversation branch
770/// (session-worker.ts `branchedServices`): a change is anchored at the main lane's tip and read back only while that
771/// anchor is on the branch in use; without one every refinement event applies.
772pub struct LocalServicesModule {
773    pub services: Arc<LocalServices>,
774    pub branch: Option<BranchSource>,
775}
776
777impl kernel_apis::ApiModule for LocalServicesModule {
778    fn prefixes(&self) -> &[&str] {
779        &["refinements.", "experiments."]
780    }
781
782    fn handle(&self, request: &kernel_apis::Request<'_>) -> Result<Value, String> {
783        let branch = match &self.branch {
784            Some(source) if request.kind.starts_with("refinements.") => Some(source()),
785            _ => None,
786        };
787        self.services
788            .handle(request.kind, &Value::Object(request.payload.clone()), branch.as_ref())
789    }
790}