1use 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"];
27const 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];
50const 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
72pub type Validator = Arc<dyn Fn(&str, &Value) -> Result<bool, String> + Send + Sync>;
75pub type Ids = Arc<dyn Fn() -> String + Send + Sync>;
77pub type OnBranch = Arc<dyn Fn(&str) -> bool + Send + Sync>;
79
80#[derive(Clone)]
82pub struct LocalOptions {
83 pub validate: Option<Validator>,
84 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#[derive(Clone, Default)]
103pub struct Branch {
104 pub anchor: Option<String>,
106 pub on_branch: Option<OnBranch>,
108}
109
110fn 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
119fn 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
144pub(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
158fn 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 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
195fn 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
207fn 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
220fn 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
234fn 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
267fn 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#[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
355fn 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 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
470fn 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
506pub struct LocalServices {
508 documents: Box<dyn KeyedDocuments>,
509 options: LocalOptions,
510 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 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 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 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
741pub type BranchSource = Arc<dyn Fn() -> Branch + Send + Sync>;
744
745pub 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
755pub type InstructionHook = Arc<dyn Fn(&str) -> Result<Vec<Value>, String> + Send + Sync>;
757
758pub 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
769pub 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}