1use kernel::store::DocumentStore;
12use kernel_apis::store::read_versioned;
13use kernel_apis::util::Clock;
14use serde_json::{Map, Value, json};
15use std::sync::{Arc, Mutex};
16
17const MAX_CHECKS: usize = 256;
18const MAX_ATTEMPTS: usize = 4096;
19const DURABILITY_ERROR: &str = "Release gate store durability is uncertain; reopen the owner";
20const OUTCOMES: [&str; 3] = ["passed", "failed", "missing"];
21
22fn valid_id(value: &str) -> bool {
24 value.as_bytes().first().is_some_and(u8::is_ascii_lowercase)
25 && value.len() <= 128
26 && value
27 .bytes()
28 .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b"._-".contains(&b))
29}
30
31fn valid_check(value: &str) -> bool {
33 value.as_bytes().first().is_some_and(u8::is_ascii_alphanumeric)
34 && value.len() <= 128
35 && value
36 .bytes()
37 .all(|b| b.is_ascii_alphanumeric() || b" ._:/-".contains(&b))
38}
39
40fn valid_hash(value: &str) -> bool {
42 value.len() == 64 && value.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
43}
44
45fn valid_variant(value: &str) -> bool {
47 value.chars().next().is_some_and(|ch| !jsrt::string::is_space(ch))
48 && !value
49 .chars()
50 .any(|ch| matches!(ch, '\n' | '\r' | '\u{2028}' | '\u{2029}'))
51 && jsrt::utf16::len(value) <= 256
52}
53
54fn plain_object<'a>(value: Option<&'a Value>, name: &str) -> Result<&'a Map<String, Value>, String> {
55 value
56 .and_then(Value::as_object)
57 .ok_or_else(|| format!("{name} must be a JSON object"))
58}
59
60fn gate_id_field(value: Option<&Value>, name: &str) -> Result<String, String> {
61 match value.and_then(Value::as_str) {
62 Some(id) if valid_id(id) => Ok(id.into()),
63 _ => Err(format!("{name} must be a short lowercase identifier")),
64 }
65}
66
67fn hash_field(value: Option<&Value>, name: &str) -> Result<String, String> {
68 match value.and_then(Value::as_str) {
69 Some(hash) if valid_hash(hash) => Ok(hash.into()),
70 _ => Err(format!("{name} must be a lowercase SHA-256 hex string")),
71 }
72}
73
74fn checks_field(value: Option<&Value>) -> Result<Vec<(String, bool)>, String> {
76 let list = value
77 .and_then(Value::as_array)
78 .filter(|list| !list.is_empty() && list.len() <= MAX_CHECKS)
79 .ok_or_else(|| format!("checks must be a list of 1 to {MAX_CHECKS} entries"))?;
80 let mut checks: Vec<(String, bool)> = Vec::new();
81 for (index, item) in list.iter().enumerate() {
82 let entry = plain_object(Some(item), &format!("checks[{index}]"))?;
83 jsrt::payload::fields(entry, &["name", "required"])?;
84 let name = entry
85 .get("name")
86 .and_then(Value::as_str)
87 .filter(|name| valid_check(name))
88 .ok_or_else(|| format!("checks[{index}].name must be a check name of at most 128 characters"))?;
89 let required = entry
90 .get("required")
91 .and_then(Value::as_bool)
92 .ok_or_else(|| format!("checks[{index}].required must be a boolean"))?;
93 if checks.iter().any(|(seen, _)| seen == name) {
94 return Err(format!("Duplicate check name: {name}"));
95 }
96 checks.push((name.into(), required));
97 }
98 if !checks.iter().any(|(_, required)| *required) {
99 return Err("A gate needs at least one required check; a gate with none could never block".into());
100 }
101 checks.sort_by(|left, right| left.0.cmp(&right.0));
102 Ok(checks)
103}
104
105fn gate_digest(id: &str, checks: &[(String, bool)], fixture_hash: &str) -> String {
106 let checks: Vec<Value> = checks.iter().map(|(name, required)| json!([name, required])).collect();
107 jsrt::hash::sha256_hex(
108 jsrt::json::stringify(&json!({"id": id, "checks": checks, "fixture_hash": fixture_hash})).as_bytes(),
109 )
110}
111
112fn gate_checks(gate: &Value) -> Vec<(String, bool)> {
113 gate["checks"]
114 .as_array()
115 .into_iter()
116 .flatten()
117 .map(|check| {
118 (
119 check["name"].as_str().unwrap_or_default().to_string(),
120 check["required"].as_bool().unwrap_or(false),
121 )
122 })
123 .collect()
124}
125
126fn run_field(value: Option<&Value>, name: &str, gate: &Value) -> Result<Value, String> {
128 let run = plain_object(value, name)?;
129 if let Some(key) = run
130 .keys()
131 .find(|key| !["variant", "fixture_hash", "results"].contains(&key.as_str()))
132 {
133 return Err(format!(
134 "Unknown field {name}.{key}: a run is {{variant, fixture_hash, results: {{check: \"passed\" | \"failed\" | \"missing\"}}}}"
135 ));
136 }
137 let variant = run
138 .get("variant")
139 .and_then(Value::as_str)
140 .filter(|variant| valid_variant(variant))
141 .ok_or_else(|| format!("{name}.variant must be a nonempty string of at most 256 characters"))?;
142 let fixture_hash = hash_field(run.get("fixture_hash"), &format!("{name}.fixture_hash"))?;
143 let supplied = plain_object(run.get("results"), &format!("{name}.results"))?;
144 let checks = gate_checks(gate);
145 for (check, outcome) in supplied {
146 if !checks.iter().any(|(known, _)| known == check) {
148 return Err(format!(
149 "{name}.results names a check the gate does not define: {check}"
150 ));
151 }
152 if !outcome.as_str().is_some_and(|o| OUTCOMES.contains(&o)) {
153 return Err(format!("{name}.results.{check} must be passed, failed, or missing"));
154 }
155 }
156 let results: Map<String, Value> = checks
157 .iter()
158 .map(|(check, _)| {
159 (
160 check.clone(),
161 supplied.get(check).cloned().unwrap_or_else(|| json!("missing")),
162 )
163 })
164 .collect();
165 Ok(json!({"variant": variant, "fixture_hash": fixture_hash, "results": results}))
166}
167
168fn judge(gate: &Value, baseline: &Value, candidate: &Value) -> (bool, Vec<String>, Vec<Value>, Vec<Value>) {
170 let mut reasons = Vec::new();
171 let mut blocked = false;
172 let gate_hash = gate["fixture_hash"].as_str().unwrap_or_default();
173 for (label, run) in [("baseline", baseline), ("candidate", candidate)] {
174 let hash = run["fixture_hash"].as_str().unwrap_or_default();
175 if hash != gate_hash {
176 blocked = true;
177 reasons.push(format!(
178 "Fixture mismatch: {label} {} ran against {hash}, gate {} requires {gate_hash}",
179 run["variant"].as_str().unwrap_or_default(),
180 gate["id"].as_str().unwrap_or_default(),
181 ));
182 }
183 }
184 let (mut regressions, mut improvements) = (Vec::new(), Vec::new());
185 for (check, required) in gate_checks(gate) {
186 let before = baseline["results"][&check].as_str().unwrap_or("missing");
187 let after = candidate["results"][&check].as_str().unwrap_or("missing");
188 let change = json!({"check": check, "required": required, "baseline": before, "candidate": after});
189 if before == "passed" && after != "passed" {
190 regressions.push(change);
191 if required {
192 blocked = true;
193 reasons.push(format!(
194 "Required check {check} regressed: passed in baseline, {after} in candidate"
195 ));
196 } else {
197 reasons.push(format!(
198 "Optional check {check} regressed ({after}); reported, not blocking"
199 ));
200 }
201 } else if before != "passed" && after == "passed" {
202 improvements.push(change);
203 } else if required && after != "passed" {
204 blocked = true;
205 reasons.push(format!("Required check {check} is {after} in candidate"));
206 }
207 }
208 if !blocked {
209 reasons.insert(
210 0,
211 format!(
212 "Every required check passed in candidate {}",
213 candidate["variant"].as_str().unwrap_or_default()
214 ),
215 );
216 }
217 (blocked, reasons, regressions, improvements)
218}
219
220fn nonempty_string(value: Option<&Value>) -> bool {
221 value.and_then(Value::as_str).is_some_and(|text| !text.is_empty())
222}
223
224fn string_or_null(value: Option<&Value>) -> bool {
225 value.is_some_and(|v| v.is_null() || nonempty_string(Some(v)))
226}
227
228fn only(map: &Map<String, Value>, keys: &[&str]) -> bool {
229 map.keys().all(|key| keys.contains(&key.as_str()))
230}
231
232fn valid_gate(gate: &Value) -> bool {
234 let Some(map) = gate.as_object() else {
235 return false;
236 };
237 only(
238 map,
239 &["id", "checks", "fixture_hash", "digest", "defined_at", "defined_by"],
240 ) && ["id", "fixture_hash", "digest"]
241 .iter()
242 .all(|key| nonempty_string(map.get(*key)))
243 && map.get("defined_at").is_some_and(Value::is_number)
244 && string_or_null(map.get("defined_by"))
245 && map.get("checks").and_then(Value::as_array).is_some_and(|checks| {
246 checks.iter().all(|check| {
247 check.as_object().is_some_and(|check| {
248 only(check, &["name", "required"])
249 && nonempty_string(check.get("name"))
250 && check.get("required").is_some_and(Value::is_boolean)
251 })
252 })
253 })
254}
255
256fn valid_outcome(value: Option<&Value>) -> bool {
257 value.and_then(Value::as_str).is_some_and(|o| OUTCOMES.contains(&o))
258}
259
260fn valid_run(run: Option<&Value>) -> bool {
262 run.and_then(Value::as_object).is_some_and(|map| {
263 only(map, &["variant", "fixture_hash", "results"])
264 && nonempty_string(map.get("variant"))
265 && nonempty_string(map.get("fixture_hash"))
266 && map
267 .get("results")
268 .and_then(Value::as_object)
269 .is_some_and(|results| results.values().all(|o| valid_outcome(Some(o))))
270 })
271}
272
273fn valid_change(change: &Value) -> bool {
275 change.as_object().is_some_and(|map| {
276 only(map, &["check", "required", "baseline", "candidate"])
277 && map.get("check").is_some_and(Value::is_string)
278 && map.get("required").is_some_and(Value::is_boolean)
279 && valid_outcome(map.get("baseline"))
280 && valid_outcome(map.get("candidate"))
281 })
282}
283
284fn valid_attempt(attempt: &Value) -> bool {
286 let Some(map) = attempt.as_object() else {
287 return false;
288 };
289 let changes = |key: &str| {
290 map.get(key)
291 .and_then(Value::as_array)
292 .is_some_and(|list| list.iter().all(valid_change))
293 };
294 only(
295 map,
296 &[
297 "id",
298 "gate_id",
299 "gate_digest",
300 "at",
301 "requester_task_id",
302 "baseline",
303 "candidate",
304 "decision",
305 "reasons",
306 "regressions",
307 "improvements",
308 ],
309 ) && ["id", "gate_id", "gate_digest"]
310 .iter()
311 .all(|key| nonempty_string(map.get(*key)))
312 && map.get("at").is_some_and(Value::is_number)
313 && string_or_null(map.get("requester_task_id"))
314 && valid_run(map.get("baseline"))
315 && valid_run(map.get("candidate"))
316 && map
317 .get("decision")
318 .and_then(Value::as_str)
319 .is_some_and(|d| d == "passed" || d == "blocked")
320 && map
321 .get("reasons")
322 .and_then(Value::as_array)
323 .is_some_and(|list| list.iter().all(Value::is_string))
324 && changes("regressions")
325 && changes("improvements")
326}
327
328fn valid_document(document: &Value) -> bool {
330 document.as_object().is_some_and(|map| {
331 only(map, &["version", "gates", "attempts"])
332 && map.get("version").and_then(Value::as_f64) == Some(1.0)
333 && map
334 .get("gates")
335 .and_then(Value::as_array)
336 .is_some_and(|gates| gates.iter().all(valid_gate))
337 && map
338 .get("attempts")
339 .and_then(Value::as_array)
340 .is_some_and(|attempts| attempts.iter().all(valid_attempt))
341 })
342}
343
344struct State {
345 document: Value,
346 loaded: Option<Result<(), String>>,
348 broken: bool,
349}
350
351pub struct ReleaseGateModule {
353 store: Arc<dyn DocumentStore>,
354 now: Option<Clock>,
356 ids: Arc<dyn Fn() -> String + Send + Sync>,
357 state: Mutex<State>,
358}
359
360impl ReleaseGateModule {
361 pub fn new(store: Arc<dyn DocumentStore>, now: Option<Clock>) -> Self {
362 ReleaseGateModule {
363 store,
364 now,
365 ids: Arc::new(jsrt::random::uuid_v4),
366 state: Mutex::new(State {
367 document: json!({"version": 1, "gates": [], "attempts": []}),
368 loaded: None,
369 broken: false,
370 }),
371 }
372 }
373
374 pub fn with_ids(mut self, ids: Arc<dyn Fn() -> String + Send + Sync>) -> Self {
376 self.ids = ids;
377 self
378 }
379
380 fn load(&self) -> Result<Value, String> {
381 let Some(saved) = read_versioned("ultron.module/release-gates", self.store.read()?, "version")? else {
382 return Ok(json!({"version": 1, "gates": [], "attempts": []}));
383 };
384 if !valid_document(&saved) {
385 return Err("Invalid release gate document".into());
386 }
387 for gate in saved["gates"].as_array().into_iter().flatten() {
388 let id = gate["id"].as_str().unwrap_or_default();
389 if gate["digest"]
390 != gate_digest(
391 id,
392 &gate_checks(gate),
393 gate["fixture_hash"].as_str().unwrap_or_default(),
394 )
395 {
396 return Err(format!("Release gate {id} definition does not match its digest"));
397 }
398 }
399 Ok(saved)
400 }
401
402 fn ready<'a>(&self, state: &'a mut State) -> Result<&'a mut State, String> {
404 if state.broken {
405 return Err(DURABILITY_ERROR.into());
406 }
407 if state.loaded.is_none() {
408 state.loaded = Some(self.load().map(|document| state.document = document));
409 }
410 state.loaded.clone().unwrap_or(Ok(()))?;
411 Ok(state)
412 }
413
414 fn write(&self, state: &mut State, next: Value) -> Result<(), String> {
415 if self.store.write(&next).is_err() {
416 state.broken = true;
417 return Err(DURABILITY_ERROR.into());
418 }
419 state.document = next;
420 Ok(())
421 }
422
423 fn find_gate(document: &Value, id: &str) -> Result<Value, String> {
424 document["gates"]
425 .as_array()
426 .and_then(|gates| gates.iter().find(|gate| gate["id"] == id))
427 .cloned()
428 .ok_or_else(|| format!("Unknown release gate: {id}"))
429 }
430
431 pub fn handle_at(
433 &self,
434 kind: &str,
435 payload: &Map<String, Value>,
436 caller: Option<&str>,
437 now: i64,
438 ) -> Result<Value, String> {
439 let now = self.now.as_ref().map_or(now, |clock| clock());
440 match kind {
441 "gates.define" => {
442 jsrt::payload::fields(payload, &["id", "checks", "fixture_hash"])?;
443 let id = gate_id_field(payload.get("id"), "id")?;
444 let checks = checks_field(payload.get("checks"))?;
445 let fixture_hash = hash_field(payload.get("fixture_hash"), "fixture_hash")?;
446 let digest = gate_digest(&id, &checks, &fixture_hash);
447 let mut guard = jsrt::sync::lock(&self.state);
448 let state = self.ready(&mut guard)?;
449 if let Ok(existing) = Self::find_gate(&state.document, &id) {
450 if existing["digest"] != digest.as_str() {
451 return Err(format!(
452 "Release gate {id} is already defined with different content and cannot be changed"
453 ));
454 }
455 return Ok(existing);
456 }
457 let checks: Vec<Value> = checks
458 .iter()
459 .map(|(name, required)| json!({"name": name, "required": required}))
460 .collect();
461 let gate = json!({
462 "id": id, "checks": checks, "fixture_hash": fixture_hash, "digest": digest,
463 "defined_at": now, "defined_by": caller,
464 });
465 let mut next = state.document.clone();
466 if let Some(gates) = next["gates"].as_array_mut() {
467 gates.push(gate.clone());
468 }
469 self.write(state, next)?;
470 Ok(gate)
471 }
472 "gates.compare" => {
473 jsrt::payload::fields(payload, &["gate_id", "baseline", "candidate"])?;
474 let gate_id = gate_id_field(payload.get("gate_id"), "gate_id")?;
475 let mut guard = jsrt::sync::lock(&self.state);
476 let state = self.ready(&mut guard)?;
477 if state.document["attempts"].as_array().map_or(0, Vec::len) >= MAX_ATTEMPTS {
478 return Err(format!("Release gate history is full ({MAX_ATTEMPTS} attempts)"));
479 }
480 let gate = Self::find_gate(&state.document, &gate_id)?;
481 let baseline = run_field(payload.get("baseline"), "baseline", &gate)?;
482 let candidate = run_field(payload.get("candidate"), "candidate", &gate)?;
483 let (blocked, reasons, regressions, improvements) = judge(&gate, &baseline, &candidate);
484 let attempt = json!({
485 "id": format!("gate-attempt-{}", (self.ids)()),
486 "gate_id": gate["id"], "gate_digest": gate["digest"], "at": now, "requester_task_id": caller,
487 "baseline": baseline, "candidate": candidate,
488 "decision": if blocked { "blocked" } else { "passed" },
489 "reasons": reasons, "regressions": regressions, "improvements": improvements,
490 });
491 let mut next = state.document.clone();
492 if let Some(attempts) = next["attempts"].as_array_mut() {
493 attempts.push(attempt.clone());
494 }
495 self.write(state, next)?;
496 Ok(attempt)
497 }
498 "gates.history" => {
499 jsrt::payload::fields(payload, &["gate_id"])?;
500 let gate_id = gate_id_field(payload.get("gate_id"), "gate_id")?;
501 let mut guard = jsrt::sync::lock(&self.state);
502 let state = self.ready(&mut guard)?;
503 let gate = Self::find_gate(&state.document, &gate_id)?;
504 let attempts: Vec<Value> = state.document["attempts"]
505 .as_array()
506 .into_iter()
507 .flatten()
508 .filter(|attempt| attempt["gate_id"] == gate_id.as_str())
509 .cloned()
510 .collect();
511 Ok(json!({"gate": gate, "attempts": attempts}))
512 }
513 "gates.list" => {
514 jsrt::payload::fields(payload, &[])?;
515 let mut guard = jsrt::sync::lock(&self.state);
516 let state = self.ready(&mut guard)?;
517 Ok(json!({"gates": state.document["gates"]}))
518 }
519 _ => Err(format!("Unknown release gate request: {kind}")),
520 }
521 }
522}
523
524impl kernel_apis::ApiModule for ReleaseGateModule {
525 fn prefixes(&self) -> &[&str] {
526 &["gates."]
527 }
528
529 fn start(&self, _host: &dyn kernel_apis::TaskHost) -> Result<(), String> {
530 let mut guard = jsrt::sync::lock(&self.state);
531 self.ready(&mut guard).map(drop)
532 }
533
534 fn handle(&self, request: &kernel_apis::Request<'_>) -> Result<Value, String> {
535 self.handle_at(request.kind, request.payload, request.caller_task, request.host.now())
536 }
537}