Skip to main content

kernel_apis/
progress.rs

1//! `progress.*` (port of `ultron/progress.ts`): evidence-based progress receipts and reassessment. Progress is
2//! inferred only from recorded evidence and task state; reassessment never raises a budget, and a completion claim
3//! is verified only by a verifier task the host ran that returned `passed: true`. The document is
4//! `{version: 1, receipts, decisions}`; a verifier still pending when the owner ended is settled as unverified on load.
5
6use crate::store::read_versioned;
7use crate::{ApiModule, Request, TaskHost};
8use kernel::store::DocumentStore;
9use serde_json::{Map, Value, json};
10use std::sync::{Arc, Mutex};
11
12const DEFAULT_STALL_AFTER_MS: i64 = 10 * 60 * 1000;
13const DEFAULT_MAX_RECEIPTS: usize = 256;
14const MAX_EVIDENCE: usize = 32;
15const MAX_METRICS: usize = 32;
16const MAX_SUMMARY: usize = 4096;
17const MAX_REF: usize = 1024;
18const DURABILITY_ERROR: &str = "Progress store durability is uncertain; reopen the owner";
19const TERMINAL: &[&str] = &["completed", "failed", "cancelled", "interrupted"];
20const CLASSIFICATIONS: &[&str] = &["progressing", "busy", "stalled", "finished"];
21const CLAIM_DECISIONS: &[&str] = &["pending", "verified", "unverified", "rejected"];
22
23fn task_id_field(value: Option<&Value>) -> Result<String, String> {
24    match value.and_then(Value::as_str) {
25        Some(text) if !jsrt::string::trim(text).is_empty() => Ok(text.to_string()),
26        _ => Err("task_id must be a nonempty string".into()),
27    }
28}
29
30fn plain_object<'a>(value: &'a Value, name: &str) -> Result<&'a Map<String, Value>, String> {
31    value.as_object().ok_or_else(|| format!("{name} must be a JSON object"))
32}
33
34/// `/^[a-z][a-z0-9_.-]{0,63}$/`
35fn valid_kind(kind: &str) -> bool {
36    let bytes = kind.as_bytes();
37    !bytes.is_empty()
38        && bytes.len() <= 64
39        && bytes[0].is_ascii_lowercase()
40        && bytes
41            .iter()
42            .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b"_.-".contains(b))
43}
44
45fn valid_sha256(text: &str) -> bool {
46    text.len() == 64 && text.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
47}
48
49fn evidence_list(value: Option<&Value>) -> Result<Vec<Value>, String> {
50    let items = value
51        .and_then(Value::as_array)
52        .filter(|items| !items.is_empty() && items.len() <= MAX_EVIDENCE)
53        .ok_or_else(|| format!("evidence must be a list of 1 to {MAX_EVIDENCE} entries"))?;
54    items
55        .iter()
56        .enumerate()
57        .map(|(index, item)| {
58            let entry = plain_object(item, &format!("evidence[{index}]"))?;
59            jsrt::payload::fields(entry, &["kind", "ref", "sha256"])?;
60            let kind = entry
61                .get("kind")
62                .and_then(Value::as_str)
63                .filter(|kind| valid_kind(kind))
64                .ok_or_else(|| format!("evidence[{index}].kind must be a short lowercase identifier"))?;
65            let reference = entry
66                .get("ref")
67                .and_then(Value::as_str)
68                .filter(|r| !jsrt::string::trim(r).is_empty() && jsrt::utf16::len(r) <= MAX_REF)
69                .ok_or_else(|| {
70                    format!("evidence[{index}].ref must be a nonempty string of at most {MAX_REF} characters")
71                })?;
72            match entry.get("sha256").filter(|sha| !sha.is_null()) {
73                Some(sha) => {
74                    let sha = sha
75                        .as_str()
76                        .filter(|sha| valid_sha256(sha))
77                        .ok_or_else(|| format!("evidence[{index}].sha256 must be a lowercase SHA-256 hex string"))?;
78                    Ok(json!({"kind": kind, "ref": reference, "sha256": sha}))
79                }
80                None => Ok(json!({"kind": kind, "ref": reference})),
81            }
82        })
83        .collect()
84}
85
86fn metrics_field(value: Option<&Value>) -> Result<Option<Value>, String> {
87    let Some(value) = value.filter(|value| !value.is_null()) else {
88        return Ok(None);
89    };
90    let metrics = plain_object(value, "metrics")?;
91    if metrics.len() > MAX_METRICS {
92        return Err(format!("metrics may hold at most {MAX_METRICS} entries"));
93    }
94    for (key, metric) in metrics {
95        let length = jsrt::utf16::len(key);
96        if length == 0 || length > 64 {
97            return Err("metric names must be 1 to 64 characters".into());
98        }
99        if !metric.is_number() {
100            return Err(format!("metric {key} must be a finite number"));
101        }
102    }
103    Ok(Some(value.clone()))
104}
105
106fn evidence_key(entry: &Value) -> String {
107    format!(
108        "{}:{}",
109        entry["kind"].as_str().unwrap_or(""),
110        entry["ref"].as_str().unwrap_or("")
111    )
112}
113
114fn nonempty_text(value: Option<&Value>) -> bool {
115    value.and_then(Value::as_str).is_some_and(|text| !text.is_empty())
116}
117
118fn text_or_null(value: Option<&Value>) -> bool {
119    value.is_some_and(|value| value.is_null() || value.as_str().is_some_and(|text| !text.is_empty()))
120}
121
122fn strings(value: Option<&Value>) -> bool {
123    value
124        .and_then(Value::as_array)
125        .is_some_and(|items| items.iter().all(Value::is_string))
126}
127
128fn exact(map: &Map<String, Value>, keys: &[&str]) -> bool {
129    map.keys().all(|key| keys.contains(&key.as_str()))
130}
131
132fn valid_receipt(receipt: &Value) -> bool {
133    let Some(r) = receipt.as_object() else {
134        return false;
135    };
136    exact(
137        r,
138        &[
139            "id",
140            "task_id",
141            "reporter_task_id",
142            "at",
143            "summary",
144            "evidence",
145            "metrics",
146            "new_evidence",
147        ],
148    ) && nonempty_text(r.get("id"))
149        && nonempty_text(r.get("task_id"))
150        && text_or_null(r.get("reporter_task_id"))
151        && r.get("at").is_some_and(Value::is_number)
152        && r.get("summary").is_some_and(Value::is_string)
153        && r.get("evidence").and_then(Value::as_array).is_some_and(|items| {
154            items.iter().all(|e| {
155                e.as_object().is_some_and(|e| {
156                    exact(e, &["kind", "ref", "sha256"])
157                        && e.get("kind").is_some_and(Value::is_string)
158                        && e.get("ref").is_some_and(Value::is_string)
159                        && e.get("sha256").is_none_or(Value::is_string)
160                })
161            })
162        })
163        && r.get("metrics")
164            .is_none_or(|m| m.as_object().is_some_and(|m| m.values().all(Value::is_number)))
165        && strings(r.get("new_evidence"))
166}
167
168fn valid_decision(decision: &Value) -> bool {
169    let Some(d) = decision.as_object() else {
170        return false;
171    };
172    let assessment = d.get("assessment").and_then(Value::as_object).is_some_and(|a| {
173        exact(a, &["classification", "reasons", "receipts"])
174            && a.get("classification")
175                .and_then(Value::as_str)
176                .is_some_and(|c| CLASSIFICATIONS.contains(&c))
177            && strings(a.get("reasons"))
178            && strings(a.get("receipts"))
179    });
180    let budget = d.get("budget").is_none_or(|b| {
181        b.as_object().is_some_and(|b| {
182            exact(b, &["requested", "decision", "reason"])
183                && b.contains_key("requested")
184                && b.get("decision") == Some(&json!("denied"))
185                && b.get("reason").is_some_and(Value::is_string)
186        })
187    });
188    let claim = d.get("claim").is_none_or(|c| {
189        c.as_object().is_some_and(|c| {
190            exact(
191                c,
192                &[
193                    "claim",
194                    "decision",
195                    "reason",
196                    "verifier",
197                    "verifier_task_id",
198                    "verifier_status",
199                ],
200            ) && c.get("claim") == Some(&json!("complete"))
201                && c.get("decision")
202                    .and_then(Value::as_str)
203                    .is_some_and(|x| CLAIM_DECISIONS.contains(&x))
204                && c.get("reason").is_some_and(Value::is_string)
205                && ["verifier", "verifier_task_id", "verifier_status"]
206                    .iter()
207                    .all(|key| c.get(*key).is_none_or(Value::is_string))
208        })
209    });
210    exact(
211        d,
212        &[
213            "id",
214            "task_id",
215            "requester_task_id",
216            "at",
217            "assessment",
218            "budget",
219            "claim",
220        ],
221    ) && nonempty_text(d.get("id"))
222        && nonempty_text(d.get("task_id"))
223        && text_or_null(d.get("requester_task_id"))
224        && d.get("at").is_some_and(Value::is_number)
225        && assessment
226        && budget
227        && claim
228}
229
230fn valid_document(document: &Value) -> bool {
231    document.as_object().is_some_and(|d| {
232        exact(d, &["version", "receipts", "decisions"])
233            && d.get("version") == Some(&json!(1))
234            && d.get("receipts")
235                .and_then(Value::as_array)
236                .is_some_and(|r| r.iter().all(valid_receipt))
237            && d.get("decisions")
238                .and_then(Value::as_array)
239                .is_some_and(|r| r.iter().all(valid_decision))
240    })
241}
242
243struct State {
244    document: Value,
245    /// The outcome of the first load, kept like TS keeps its loading promise.
246    loaded: Option<Result<(), String>>,
247    broken: bool,
248}
249
250pub struct ProgressModule {
251    store: Arc<dyn DocumentStore>,
252    stall_after_ms: i64,
253    max_receipts: usize,
254    state: Mutex<State>,
255}
256
257impl ProgressModule {
258    pub fn new(store: Arc<dyn DocumentStore>) -> Self {
259        Self::with_limits(store, DEFAULT_STALL_AFTER_MS, DEFAULT_MAX_RECEIPTS)
260    }
261
262    /// `stallAfterMs` and `maxReceiptsPerTask`.
263    pub fn with_limits(store: Arc<dyn DocumentStore>, stall_after_ms: i64, max_receipts: usize) -> Self {
264        Self {
265            store,
266            stall_after_ms,
267            max_receipts,
268            state: Mutex::new(State {
269                document: json!({"version": 1, "receipts": [], "decisions": []}),
270                loaded: None,
271                broken: false,
272            }),
273        }
274    }
275
276    fn write(&self, state: &mut State, next: Value) -> Result<(), String> {
277        if self.store.write(&next).is_err() {
278            state.broken = true;
279            return Err(DURABILITY_ERROR.into());
280        }
281        state.document = next;
282        Ok(())
283    }
284
285    fn load(&self, state: &mut State) -> Result<(), String> {
286        let Some(saved) = read_versioned("ultron.module/progress", self.store.read()?, "version")? else {
287            return Ok(());
288        };
289        if !valid_document(&saved) {
290            return Err("Invalid progress document".into());
291        }
292        let pending = |d: &Value| d["claim"]["decision"] == "pending";
293        let decisions = saved["decisions"].as_array().cloned().unwrap_or_default();
294        if !decisions.iter().any(pending) {
295            state.document = saved;
296            return Ok(());
297        }
298        // A verifier that was still running when the owner ended produced no evidence of success.
299        let mut next = saved.clone();
300        next["decisions"] = decisions
301            .into_iter()
302            .map(|mut decision| {
303                if pending(&decision) {
304                    decision["claim"]["decision"] = "unverified".into();
305                    decision["claim"]["reason"] = "Owner ended before the verifier returned".into();
306                }
307                decision
308            })
309            .collect();
310        self.write(state, next)
311    }
312
313    /// Runs `change` on the loaded document, one at a time (TS `enqueue`).
314    fn enqueue<T>(&self, change: impl FnOnce(&mut State) -> Result<T, String>) -> Result<T, String> {
315        let mut state = jsrt::sync::lock(&self.state);
316        if state.broken {
317            return Err(DURABILITY_ERROR.into());
318        }
319        if state.loaded.is_none() {
320            let outcome = self.load(&mut state);
321            state.loaded = Some(outcome);
322        }
323        state.loaded.clone().expect("loaded")?;
324        if state.broken {
325            return Err(DURABILITY_ERROR.into());
326        }
327        change(&mut state)
328    }
329
330    fn find_task(host: &dyn TaskHost, task_id: &str) -> Result<(Value, Vec<Value>), String> {
331        let all = host.tasks()?;
332        let task = all
333            .iter()
334            .find(|task| task["id"] == task_id)
335            .cloned()
336            .ok_or("Unknown Ultron task")?;
337        Ok((task, all))
338    }
339
340    /// The caller itself, the root agent, or any ancestor of the task may inspect and reassess it.
341    fn owner_or_ancestor(caller: Option<&str>, task: &Value, all: &[Value]) -> Result<(), String> {
342        let Some(caller) = caller else {
343            return Ok(());
344        };
345        if task["id"] == caller {
346            return Ok(());
347        }
348        let mut seen = std::collections::HashSet::new();
349        let mut parent = task["parentId"].as_str().map(str::to_string);
350        while let Some(id) = parent {
351            if id == caller {
352                return Ok(());
353            }
354            if !seen.insert(id.clone()) {
355                break;
356            }
357            parent = all
358                .iter()
359                .find(|candidate| candidate["id"] == id.as_str())
360                .and_then(|candidate| candidate["parentId"].as_str().map(str::to_string));
361        }
362        Err("Caller may only access its own progress or that of its descendants".into())
363    }
364
365    fn receipts_of(document: &Value, task_id: &str) -> Vec<Value> {
366        document["receipts"]
367            .as_array()
368            .into_iter()
369            .flatten()
370            .filter(|receipt| receipt["task_id"] == task_id)
371            .cloned()
372            .collect()
373    }
374
375    fn assess(&self, document: &Value, task: &Value, now: i64) -> Value {
376        let task_id = task["id"].as_str().unwrap_or_default();
377        let task_state = task["state"].as_str().unwrap_or_default();
378        let receipts = Self::receipts_of(document, task_id);
379        let ids = |items: &[&Value]| -> Vec<Value> { items.iter().map(|r| r["id"].clone()).collect() };
380        let mut out = json!({
381            "task_id": task_id,
382            "task_state": task["state"],
383            "stall_after_ms": self.stall_after_ms,
384            "assessed_at": now,
385            "verification": "unverified",
386        });
387        let all: Vec<&Value> = receipts.iter().collect();
388        if TERMINAL.contains(&task_state) {
389            out["classification"] = "finished".into();
390            let result = task.get("result").filter(|result| !result.is_null());
391            if let Some(result) = result {
392                out["result_status"] = result["status"].clone();
393            }
394            let with = result
395                .map(|result| format!(" with result {}", result["status"].as_str().unwrap_or("")))
396                .unwrap_or_default();
397            out["reasons"] = json!([
398                format!("Task is {task_state}{with}"),
399                "A terminal state is not verification; only a passing verifier can verify completion",
400            ]);
401            out["receipts"] = Value::Array(ids(&all));
402            return out;
403        }
404        let at = |receipt: &Value| receipt["at"].as_i64().unwrap_or(0);
405        let recent: Vec<&Value> = receipts
406            .iter()
407            .filter(|receipt| now - at(receipt) <= self.stall_after_ms)
408            .collect();
409        if recent.is_empty() {
410            let last = receipts.last();
411            out["classification"] = "stalled".into();
412            let reason = match last {
413                None => format!("Task is {task_state} and has never reported progress"),
414                Some(last) => format!(
415                    "Task is {task_state} and its last receipt is {}ms old, beyond the {}ms window",
416                    now - at(last),
417                    self.stall_after_ms
418                ),
419            };
420            out["reasons"] = json!([reason]);
421            out["receipts"] = json!(last.map(|last| vec![last["id"].clone()]).unwrap_or_default());
422            return out;
423        }
424        let novel: Vec<&Value> = recent
425            .iter()
426            .copied()
427            .filter(|receipt| receipt["new_evidence"].as_array().is_some_and(|n| !n.is_empty()))
428            .collect();
429        if !novel.is_empty() {
430            out["classification"] = "progressing".into();
431            out["reasons"] = novel
432                .iter()
433                .map(|receipt| {
434                    let keys: Vec<&str> = receipt["new_evidence"]
435                        .as_array()
436                        .into_iter()
437                        .flatten()
438                        .filter_map(Value::as_str)
439                        .collect();
440                    Value::from(format!(
441                        "Receipt {} added new or changed evidence: {}",
442                        receipt["id"].as_str().unwrap_or(""),
443                        keys.join(", ")
444                    ))
445                })
446                .collect();
447            out["receipts"] = Value::Array(ids(&novel));
448            return out;
449        }
450        out["classification"] = "busy".into();
451        out["reasons"] = json!([format!(
452            "{} receipt(s) within {}ms repeated previously seen evidence; activity is not progress",
453            recent.len(),
454            self.stall_after_ms
455        )]);
456        out["receipts"] = Value::Array(ids(&recent));
457        out
458    }
459
460    fn report(&self, request: &Request<'_>) -> Result<Value, String> {
461        let payload = request.payload;
462        kernel::ops::fields(request.kind, payload)?;
463        let caller = request.caller_task;
464        let task_id = match payload.get("task_id").filter(|value| !value.is_null()) {
465            None => caller.map(str::to_string),
466            value => Some(task_id_field(value)?),
467        };
468        let task_id = task_id.ok_or("The root agent must name the task_id it reports for")?;
469        let summary = payload
470            .get("summary")
471            .and_then(Value::as_str)
472            .filter(|s| !jsrt::string::trim(s).is_empty() && jsrt::utf16::len(s) <= MAX_SUMMARY)
473            .ok_or_else(|| format!("summary must be a nonempty string of at most {MAX_SUMMARY} characters"))?;
474        let evidence = evidence_list(payload.get("evidence"))?;
475        let metrics = metrics_field(payload.get("metrics"))?;
476        let (task, _) = Self::find_task(request.host, &task_id)?;
477        if task["id"] != caller.map(Value::from).unwrap_or(Value::Null) && task["parentId"].as_str() != caller {
478            return Err("Caller may only report progress for itself or its direct children".into());
479        }
480        self.enqueue(|state| {
481            let previous = Self::receipts_of(&state.document, &task_id);
482            if previous.len() >= self.max_receipts {
483                return Err(format!(
484                    "Task {task_id} already has the maximum of {} progress receipts",
485                    self.max_receipts
486                ));
487            }
488            let mut known: Vec<(String, Option<String>)> = Vec::new();
489            for receipt in &previous {
490                for entry in receipt["evidence"].as_array().into_iter().flatten() {
491                    let key = evidence_key(entry);
492                    let sha = entry["sha256"].as_str().map(str::to_string);
493                    match known.iter_mut().find(|(k, _)| *k == key) {
494                        Some(slot) => slot.1 = sha.or(slot.1.take()),
495                        None => known.push((key, sha)),
496                    }
497                }
498            }
499            let mut fresh: Vec<String> = Vec::new();
500            for entry in &evidence {
501                let key = evidence_key(entry);
502                let seen = known.iter().find(|(k, _)| *k == key);
503                let changed = entry["sha256"]
504                    .as_str()
505                    .is_some_and(|sha| seen.and_then(|(_, known)| known.as_deref()) != Some(sha));
506                if (seen.is_none() || changed) && !fresh.contains(&key) {
507                    fresh.push(key);
508                }
509            }
510            let mut receipt = json!({
511                "id": format!("progress-receipt-{}", jsrt::random::uuid_v4()),
512                "task_id": task_id,
513                "reporter_task_id": caller,
514                "at": request.host.now(),
515                "summary": summary,
516                "evidence": evidence,
517            });
518            if let Some(metrics) = metrics {
519                receipt["metrics"] = metrics;
520            }
521            receipt["new_evidence"] = json!(fresh);
522            let mut next = state.document.clone();
523            if let Some(Value::Array(receipts)) = next.get_mut("receipts") {
524                receipts.push(receipt.clone());
525            }
526            self.write(state, next)?;
527            Ok(receipt)
528        })
529    }
530
531    fn record_decision(&self, decision: &Value) -> Result<(), String> {
532        self.enqueue(|state| {
533            let mut next = state.document.clone();
534            if let Some(Value::Array(decisions)) = next.get_mut("decisions") {
535                decisions.push(decision.clone());
536            }
537            self.write(state, next)
538        })
539    }
540
541    fn verify(request: &Request<'_>, task: &Value, verifier: &str, input: Value, caller: Option<&str>) -> Value {
542        let host = request.host;
543        let mut claim = json!({"claim": "complete", "verifier": verifier});
544        let spawned = host.spawn(&json!({"definition": verifier, "input": input}), caller);
545        let verifier_task_id = match spawned {
546            Ok(task) => task["id"].as_str().unwrap_or_default().to_string(),
547            Err(error) => {
548                claim["decision"] = "unverified".into();
549                claim["reason"] = format!("Verifier could not be started: {error}").into();
550                return claim;
551            }
552        };
553        claim["verifier_task_id"] = verifier_task_id.clone().into();
554        let result = match host.result(&verifier_task_id) {
555            Ok(result) => result,
556            Err(error) => {
557                claim["decision"] = "unverified".into();
558                claim["reason"] = format!("Verifier result is unavailable: {error}").into();
559                return claim;
560            }
561        };
562        let status = result["status"].as_str().unwrap_or_default().to_string();
563        claim["verifier_status"] = status.clone().into();
564        if status != "succeeded" {
565            let error = result["error"]
566                .as_str()
567                .filter(|e| !e.is_empty())
568                .map(|e| format!(": {e}"))
569                .unwrap_or_default();
570            claim["decision"] = "unverified".into();
571            claim["reason"] = format!("Verifier {status}{error}").into();
572            return claim;
573        }
574        let passed = result
575            .get("value")
576            .and_then(Value::as_object)
577            .and_then(|v| v.get("passed"));
578        let (decision, reason) = match passed {
579            Some(Value::Bool(true)) => (
580                "verified",
581                format!(
582                    "Verifier {verifier} passed for task {}",
583                    task["id"].as_str().unwrap_or("")
584                ),
585            ),
586            Some(Value::Bool(false)) => ("unverified", format!("Verifier {verifier} did not pass")),
587            _ => ("unverified", "Verifier output has no boolean passed field".to_string()),
588        };
589        claim["decision"] = decision.into();
590        claim["reason"] = reason.into();
591        claim
592    }
593
594    fn reassess(&self, request: &Request<'_>) -> Result<Value, String> {
595        let payload = request.payload;
596        kernel::ops::fields(request.kind, payload)?;
597        let task_id = task_id_field(payload.get("task_id"))?;
598        let present = |key: &str| payload.get(key).filter(|value| !value.is_null());
599        let extend = present("extend_budget");
600        if extend.is_some_and(|e| !e.is_boolean() && !e.is_object()) {
601            return Err("extend_budget must be a boolean or a JSON object".into());
602        }
603        let claim = present("claim");
604        if claim.is_some_and(|c| c != "complete") {
605            return Err("claim must be \"complete\"".into());
606        }
607        let verifier = present("verifier");
608        if verifier.is_some_and(|v| !v.as_str().is_some_and(crate::util::valid_definition)) {
609            return Err("verifier must be id@version".into());
610        }
611        let verifier = verifier.and_then(Value::as_str);
612        let verifier_input = present("verifier_input");
613        if (verifier.is_some() || verifier_input.is_some()) && claim.is_none() {
614            return Err("verifier and verifier_input require claim".into());
615        }
616        let caller = request.caller_task;
617        let (task, all) = Self::find_task(request.host, &task_id)?;
618        Self::owner_or_ancestor(caller, &task, &all)?;
619        let assessment = self.enqueue(|state| Ok(self.assess(&state.document, &task, request.host.now())))?;
620        let mut decision = json!({
621            "id": format!("progress-decision-{}", jsrt::random::uuid_v4()),
622            "task_id": task_id,
623            "requester_task_id": caller,
624            "at": request.host.now(),
625            "assessment": {
626                "classification": assessment["classification"],
627                "reasons": assessment["reasons"],
628                "receipts": assessment["receipts"],
629            },
630        });
631        if let Some(extend) = extend.filter(|e| **e != Value::Bool(false)) {
632            decision["budget"] = json!({
633                "requested": extend,
634                "decision": "denied",
635                "reason": "Budgets are fixed at admission; progress reassessment cannot extend them",
636            });
637        }
638        if claim.is_none() {
639            self.record_decision(&decision)?;
640            return Ok(decision);
641        }
642        let state = task["state"].as_str().unwrap_or_default();
643        if state != "completed" || task["result"]["status"] != "succeeded" {
644            decision["claim"] = json!({
645                "claim": "complete",
646                "decision": "rejected",
647                "reason": format!("Task is {state}; only a succeeded task can be claimed complete"),
648            });
649            self.record_decision(&decision)?;
650            return Ok(decision);
651        }
652        let Some(verifier) = verifier else {
653            decision["claim"] = json!({
654                "claim": "complete",
655                "decision": "unverified",
656                "reason": "No verifier was named; a task result alone is not verification",
657            });
658            self.record_decision(&decision)?;
659            return Ok(decision);
660        };
661        // Record the intent first so an owner crash mid-verification leaves an unverified trace.
662        decision["claim"] =
663            json!({"claim": "complete", "decision": "pending", "reason": "Verifier running", "verifier": verifier});
664        self.record_decision(&decision)?;
665        let input = match verifier_input {
666            Some(input) => input.clone(),
667            None => {
668                let evidence: Vec<Value> = {
669                    let state = jsrt::sync::lock(&self.state);
670                    Self::receipts_of(&state.document, &task_id)
671                        .iter()
672                        .flat_map(|receipt| receipt["evidence"].as_array().cloned().unwrap_or_default())
673                        .collect()
674                };
675                let result = task["result"].get("value").cloned().unwrap_or(Value::Null);
676                json!({"task_id": task_id, "result": result, "evidence": evidence})
677            }
678        };
679        let outcome = Self::verify(request, &task, verifier, input, caller);
680        let id = decision["id"].clone();
681        self.enqueue(|state| {
682            let mut next = state.document.clone();
683            let mut updated = Value::Null;
684            if let Some(Value::Array(decisions)) = next.get_mut("decisions") {
685                for decision in decisions.iter_mut().filter(|d| d["id"] == id) {
686                    decision["claim"] = outcome.clone();
687                    updated = decision.clone();
688                }
689            }
690            self.write(state, next)?;
691            Ok(updated)
692        })
693    }
694
695    fn history(&self, request: &Request<'_>) -> Result<Value, String> {
696        kernel::ops::fields(request.kind, request.payload)?;
697        let task_id = task_id_field(request.payload.get("task_id"))?;
698        let (task, all) = Self::find_task(request.host, &task_id)?;
699        Self::owner_or_ancestor(request.caller_task, &task, &all)?;
700        self.enqueue(|state| {
701            let decisions: Vec<Value> = state.document["decisions"]
702                .as_array()
703                .into_iter()
704                .flatten()
705                .filter(|decision| decision["task_id"] == task_id.as_str())
706                .cloned()
707                .collect();
708            Ok(json!({
709                "task_id": task_id,
710                "receipts": Self::receipts_of(&state.document, &task_id),
711                "decisions": decisions,
712            }))
713        })
714    }
715
716    fn assess_request(&self, request: &Request<'_>) -> Result<Value, String> {
717        kernel::ops::fields(request.kind, request.payload)?;
718        let task_id = task_id_field(request.payload.get("task_id"))?;
719        let (task, all) = Self::find_task(request.host, &task_id)?;
720        Self::owner_or_ancestor(request.caller_task, &task, &all)?;
721        self.enqueue(|state| Ok(self.assess(&state.document, &task, request.host.now())))
722    }
723
724    /// The stored document (loading it first).
725    pub fn document(&self) -> Result<Value, String> {
726        self.enqueue(|state| Ok(state.document.clone()))
727    }
728}
729
730impl ApiModule for ProgressModule {
731    fn prefixes(&self) -> &[&str] {
732        &["progress."]
733    }
734
735    fn start(&self, _host: &dyn TaskHost) -> Result<(), String> {
736        self.enqueue(|_| Ok(()))
737    }
738
739    fn handle(&self, request: &Request<'_>) -> Result<Value, String> {
740        match request.kind {
741            "progress.report" => self.report(request),
742            "progress.assess" => self.assess_request(request),
743            "progress.reassess" => self.reassess(request),
744            "progress.history" => self.history(request),
745            other => Err(format!("Unknown progress request: {other}")),
746        }
747    }
748}