Skip to main content

glass_browser/browser/session/
workflow.rs

1//! Versioned, declarative workflow definitions.
2//!
3//! This module contains the validated workflow contract, execution evidence,
4//! bounded checkpointing, and resume reconciliation.
5
6use super::types::{BatchMode, BatchStep, BrowserResult, VerificationPredicate};
7use super::{
8    INTENT_RESOLUTION_SCHEMA_VERSION, IntentConfidence, IntentConstraints, IntentPolicyDecision,
9    IntentScope, SemanticIntentAction, SemanticIntentExecutionRequest, SemanticIntentRequest,
10    SemanticIntentResult, SemanticResolution, SemanticResolutionPolicy, SemanticRouteIdentity,
11    target_fingerprint_digest,
12};
13use serde::de::Error as DeError;
14use serde::{Deserialize, Deserializer, Serialize, Serializer};
15use serde_json::Value;
16use sha2::{Digest, Sha256};
17use std::collections::{BTreeMap, BTreeSet};
18use std::fmt;
19use std::time::{Duration, Instant};
20use url::Url;
21
22mod checkpoint;
23pub use checkpoint::*;
24mod recorder;
25pub use recorder::*;
26
27/// The workflow definition schema understood by this crate.
28pub const WORKFLOW_SCHEMA_VERSION: u32 = 1;
29const MAX_NAME_BYTES: usize = 128;
30const MAX_DESCRIPTION_BYTES: usize = 4 * 1024;
31const MAX_INPUTS: usize = 64;
32const MAX_STEPS: usize = 64;
33const MAX_DURATION_MS: u64 = 15 * 60 * 1_000;
34const MAX_RETRIES: u32 = 8;
35const MAX_EXTRACTED_BYTES: usize = 4 * 1024 * 1024;
36const MAX_TEXT_BYTES: usize = 64 * 1024;
37const MAX_TARGET_BYTES: usize = 1_024;
38const MAX_WAIT_CONDITION_BYTES: usize = 4 * 1024;
39const MAX_STEP_REPETITIONS: u32 = 8;
40const MAX_WORKFLOW_TRACE_EVENTS: usize = 2_048;
41const WORKFLOW_TRACE_SCHEMA_VERSION: u8 = 1;
42const WORKFLOW_CHECKPOINT_SCHEMA_VERSION: u8 = 1;
43const MAX_WORKFLOW_CHECKPOINT_BYTES: usize = 8 * 1024;
44const MAX_CHECKPOINT_HISTORY_STATES: usize = 64;
45const MAX_CHECKPOINT_EXECUTION_IDS: usize = 8;
46const MAX_INTENT_PURPOSE_BYTES: usize = 256;
47
48/// A complete declarative workflow.
49#[derive(Debug, Clone, Serialize, Deserialize)]
50#[serde(rename_all = "camelCase")]
51pub struct WorkflowDefinition {
52    /// Schema version, independent of the workflow's business version.
53    pub schema_version: u32,
54    /// Stable human-readable workflow name.
55    pub name: String,
56    /// Caller-owned version of this workflow definition.
57    pub workflow_version: String,
58    #[serde(default, skip_serializing_if = "Option::is_none")]
59    pub description: Option<String>,
60    pub inputs: BTreeMap<String, WorkflowInput>,
61    pub budgets: WorkflowBudgets,
62    #[serde(default)]
63    pub preconditions: Vec<VerificationPredicate>,
64    pub steps: Vec<WorkflowStep>,
65    pub terminal_condition: VerificationPredicate,
66    pub outputs: BTreeMap<String, WorkflowOutputDeclaration>,
67}
68
69impl WorkflowDefinition {
70    /// Parse and validate a JSON workflow definition.
71    pub fn from_json(input: &str) -> Result<Self, WorkflowValidationError> {
72        let value: Value = serde_json::from_str(input)
73            .map_err(|error| WorkflowValidationError::new("$", format!("invalid JSON: {error}")))?;
74        Self::from_value(value)
75    }
76
77    /// Deserialize and validate a workflow definition from JSON data.
78    pub fn from_value(value: Value) -> Result<Self, WorkflowValidationError> {
79        require_object_fields(
80            &value,
81            &[
82                "schemaVersion",
83                "name",
84                "workflowVersion",
85                "inputs",
86                "budgets",
87                "steps",
88                "terminalCondition",
89                "outputs",
90            ],
91        )?;
92        reject_unknown_fields(
93            &value,
94            "$",
95            &[
96                "schemaVersion",
97                "name",
98                "workflowVersion",
99                "description",
100                "inputs",
101                "budgets",
102                "preconditions",
103                "steps",
104                "terminalCondition",
105                "outputs",
106            ],
107        )?;
108        if let Some(inputs) = value.get("inputs").and_then(Value::as_object) {
109            for (name, input) in inputs {
110                reject_unknown_fields(
111                    input,
112                    &format!("inputs.{name}"),
113                    &["valueType", "type", "required", "maxLength", "sensitive"],
114                )?;
115            }
116        }
117        if let Some(budgets) = value.get("budgets") {
118            reject_unknown_fields(
119                budgets,
120                "budgets",
121                &[
122                    "maxSteps",
123                    "maxDurationMs",
124                    "maxRetries",
125                    "maxExtractedBytes",
126                ],
127            )?;
128        }
129        if let Some(outputs) = value.get("outputs").and_then(Value::as_object) {
130            for (name, output) in outputs {
131                reject_unknown_fields(
132                    output,
133                    &format!("outputs.{name}"),
134                    &["valueType", "type", "source", "required", "sensitive"],
135                )?;
136            }
137        }
138        if let Some(preconditions) = value.get("preconditions").and_then(Value::as_array) {
139            for (index, predicate) in preconditions.iter().enumerate() {
140                reject_predicate_fields(predicate, &format!("preconditions[{index}]"))?;
141            }
142        }
143        if let Some(predicate) = value.get("terminalCondition") {
144            reject_predicate_fields(predicate, "terminalCondition")?;
145        }
146        if let Some(steps) = value.get("steps").and_then(Value::as_array) {
147            for (index, step) in steps.iter().enumerate() {
148                reject_unknown_fields(
149                    step,
150                    &format!("steps[{index}]"),
151                    &[
152                        "id",
153                        "action",
154                        "intent",
155                        "when",
156                        "expect",
157                        "beforeRetry",
158                        "transaction",
159                        "idempotencyKey",
160                        "maxRetries",
161                        "repeat",
162                        "url",
163                        "timeoutMs",
164                        "target",
165                        "text",
166                        "value",
167                        "condition",
168                        "dx",
169                        "dy",
170                        "includeDom",
171                        "includeScreenshot",
172                        "includeFormValues",
173                    ],
174                )?;
175                if let Some(intent) = step.get("intent") {
176                    if step.get("action").is_some() {
177                        return Err(WorkflowValidationError::new(
178                            format!("steps[{index}].action"),
179                            "semantic intent steps cannot also declare a batch action",
180                        ));
181                    }
182                    reject_unknown_fields(
183                        intent,
184                        &format!("steps[{index}].intent"),
185                        &[
186                            "action",
187                            "purpose",
188                            "intent",
189                            "scope",
190                            "constraints",
191                            "resolutionPolicy",
192                            "value",
193                        ],
194                    )?;
195                }
196                for field in ["when", "expect", "beforeRetry"] {
197                    if let Some(predicate) = step.get(field) {
198                        reject_predicate_fields(predicate, &format!("steps[{index}].{field}"))?;
199                    }
200                }
201            }
202        }
203        let definition: Self = serde_json::from_value(value).map_err(|error| {
204            WorkflowValidationError::new("$", format!("invalid workflow shape: {error}"))
205        })?;
206        definition.validate()?;
207        Ok(definition)
208    }
209
210    /// Validate all structural and resource-boundary constraints.
211    pub fn validate(&self) -> Result<(), WorkflowValidationError> {
212        if self.schema_version != WORKFLOW_SCHEMA_VERSION {
213            return Err(WorkflowValidationError::new(
214                "schemaVersion",
215                format!(
216                    "unsupported schema version {}; expected {}",
217                    self.schema_version, WORKFLOW_SCHEMA_VERSION
218                ),
219            ));
220        }
221        validate_name("name", &self.name)?;
222        validate_name("workflowVersion", &self.workflow_version)?;
223        if let Some(description) = &self.description {
224            validate_bytes("description", description, 1, MAX_DESCRIPTION_BYTES)?;
225        }
226        if self.inputs.len() > MAX_INPUTS {
227            return Err(WorkflowValidationError::new(
228                "inputs",
229                format!("must contain at most {MAX_INPUTS} entries"),
230            ));
231        }
232        for (name, input) in &self.inputs {
233            validate_map_key("inputs", name)?;
234            input.validate(&format!("inputs.{name}"))?;
235        }
236        self.budgets.validate("budgets")?;
237        if self.steps.is_empty() {
238            return Err(WorkflowValidationError::new(
239                "steps",
240                "must contain at least one step",
241            ));
242        }
243        if self.steps.len() > self.budgets.max_steps as usize {
244            return Err(WorkflowValidationError::new(
245                "steps",
246                "step count exceeds budgets.maxSteps",
247            ));
248        }
249        let expanded_steps: usize = self.steps.iter().map(|step| step.repeat as usize).sum();
250        if expanded_steps > self.budgets.max_steps as usize {
251            return Err(WorkflowValidationError::new(
252                "steps",
253                "expanded repetition count exceeds budgets.maxSteps",
254            ));
255        }
256
257        let mut ids = BTreeSet::new();
258        let mut idempotency_keys = BTreeSet::new();
259        for (index, step) in self.steps.iter().enumerate() {
260            let path = format!("steps[{index}]");
261            step.validate(&path, self.budgets.max_retries)?;
262            if !ids.insert(step.id.as_str()) {
263                return Err(WorkflowValidationError::new(
264                    format!("{path}.id"),
265                    format!("duplicate step ID {:?}", step.id),
266                ));
267            }
268            if let Some(key) = &step.idempotency_key
269                && !idempotency_keys.insert(key.as_str())
270            {
271                return Err(WorkflowValidationError::new(
272                    format!("{path}.idempotencyKey"),
273                    format!("duplicate idempotency key {:?}", key),
274                ));
275            }
276        }
277        for (index, predicate) in self.preconditions.iter().enumerate() {
278            validate_predicate(predicate, &format!("preconditions[{index}]"))?;
279        }
280        validate_predicate(&self.terminal_condition, "terminalCondition")?;
281        for (name, output) in &self.outputs {
282            validate_map_key("outputs", name)?;
283            output.validate(&format!("outputs.{name}"))?;
284        }
285        Ok(())
286    }
287
288    /// Return stable JSON suitable for hashing, caching, or audit records.
289    pub fn to_canonical_json(&self) -> Result<String, WorkflowValidationError> {
290        self.validate()?;
291        serde_json::to_string(self).map_err(|error| {
292            WorkflowValidationError::new("$", format!("cannot serialize workflow: {error}"))
293        })
294    }
295
296    /// Validate caller-provided input values before execution starts.
297    pub fn validate_inputs(
298        &self,
299        values: &BTreeMap<String, Value>,
300    ) -> Result<(), WorkflowValidationError> {
301        for name in values.keys() {
302            if !self.inputs.contains_key(name) {
303                return Err(WorkflowValidationError::new(
304                    format!("inputs.{name}"),
305                    "value has no declared input",
306                ));
307            }
308        }
309        for (name, declaration) in &self.inputs {
310            match values.get(name) {
311                Some(value) => declaration.validate_value(&format!("inputs.{name}"), value)?,
312                None if declaration.required => {
313                    return Err(WorkflowValidationError::new(
314                        format!("inputs.{name}"),
315                        "required input is missing",
316                    ));
317                }
318                None => {}
319            }
320        }
321        Ok(())
322    }
323
324    /// Resolve bounded `${inputs.name}` placeholders in declared actions.
325    /// Resolution happens before browser startup or dispatch and never
326    /// evaluates arbitrary expressions.
327    pub fn resolve_actions(
328        &self,
329        values: &BTreeMap<String, Value>,
330    ) -> Result<Vec<WorkflowStep>, WorkflowValidationError> {
331        self.validate_inputs(values)?;
332        self.steps
333            .iter()
334            .enumerate()
335            .map(|(index, step)| {
336                let mut resolved = step.clone();
337                if let Some(intent) = &step.intent {
338                    resolved.intent = Some(resolve_workflow_intent(
339                        intent,
340                        values,
341                        &format!("steps[{index}].intent"),
342                    )?);
343                } else {
344                    resolved.action = resolve_batch_step(
345                        &step.action,
346                        values,
347                        &format!("steps[{index}].action"),
348                    )?;
349                }
350                resolved.validate(&format!("steps[{index}]"), self.budgets.max_retries)?;
351                Ok(resolved)
352            })
353            .collect()
354    }
355}
356
357/// A declared workflow input and its accepted JSON type.
358#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
359#[serde(rename_all = "camelCase")]
360pub struct WorkflowInput {
361    #[serde(alias = "type")]
362    pub value_type: WorkflowValueType,
363    #[serde(default = "default_true")]
364    pub required: bool,
365    #[serde(default, skip_serializing_if = "Option::is_none")]
366    pub max_length: Option<usize>,
367    #[serde(default, skip_serializing_if = "Option::is_none")]
368    pub sensitive: Option<bool>,
369}
370
371impl WorkflowInput {
372    fn validate(&self, path: &str) -> Result<(), WorkflowValidationError> {
373        if self.max_length == Some(0) || self.max_length.is_some_and(|value| value > MAX_TEXT_BYTES)
374        {
375            return Err(WorkflowValidationError::new(
376                format!("{path}.maxLength"),
377                format!("must be 1..={MAX_TEXT_BYTES}"),
378            ));
379        }
380        Ok(())
381    }
382
383    fn validate_value(&self, path: &str, value: &Value) -> Result<(), WorkflowValidationError> {
384        let valid = match self.value_type {
385            WorkflowValueType::String => value.is_string(),
386            WorkflowValueType::Integer => value.as_i64().is_some() || value.as_u64().is_some(),
387            WorkflowValueType::Number => value.is_number(),
388            WorkflowValueType::Boolean => value.is_boolean(),
389            WorkflowValueType::Url => value
390                .as_str()
391                .is_some_and(|value| Url::parse(value).is_ok()),
392        };
393        if !valid {
394            return Err(WorkflowValidationError::new(
395                path,
396                format!("expected {}", self.value_type),
397            ));
398        }
399        if let Some(max_length) = self.max_length {
400            let length = value
401                .as_str()
402                .map_or_else(|| value.to_string().len(), str::len);
403            if length > max_length {
404                return Err(WorkflowValidationError::new(
405                    path,
406                    format!("value exceeds maxLength {max_length}"),
407                ));
408            }
409        }
410        Ok(())
411    }
412}
413
414fn default_true() -> bool {
415    true
416}
417
418/// Runtime resource limits for a workflow.
419#[derive(Debug, Clone, Serialize, Deserialize)]
420#[serde(rename_all = "camelCase")]
421pub struct WorkflowBudgets {
422    pub max_steps: u32,
423    pub max_duration_ms: u64,
424    #[serde(default)]
425    pub max_retries: u32,
426    pub max_extracted_bytes: usize,
427}
428
429impl WorkflowBudgets {
430    fn validate(&self, path: &str) -> Result<(), WorkflowValidationError> {
431        if self.max_steps == 0 || self.max_steps as usize > MAX_STEPS {
432            return Err(WorkflowValidationError::new(
433                format!("{path}.maxSteps"),
434                format!("must be 1..={MAX_STEPS}"),
435            ));
436        }
437        if self.max_duration_ms == 0 || self.max_duration_ms > MAX_DURATION_MS {
438            return Err(WorkflowValidationError::new(
439                format!("{path}.maxDurationMs"),
440                format!("must be 1..={MAX_DURATION_MS}"),
441            ));
442        }
443        if self.max_retries > MAX_RETRIES {
444            return Err(WorkflowValidationError::new(
445                format!("{path}.maxRetries"),
446                format!("must be <= {MAX_RETRIES}"),
447            ));
448        }
449        if self.max_extracted_bytes == 0 || self.max_extracted_bytes > MAX_EXTRACTED_BYTES {
450            return Err(WorkflowValidationError::new(
451                format!("{path}.maxExtractedBytes"),
452                format!("must be 1..={MAX_EXTRACTED_BYTES}"),
453            ));
454        }
455        Ok(())
456    }
457}
458
459/// JSON value types supported by workflow inputs and outputs.
460#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
461#[serde(rename_all = "snake_case")]
462pub enum WorkflowValueType {
463    String,
464    Integer,
465    Number,
466    Boolean,
467    Url,
468}
469
470impl fmt::Display for WorkflowValueType {
471    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
472        formatter.write_str(match self {
473            Self::String => "string",
474            Self::Integer => "integer",
475            Self::Number => "number",
476            Self::Boolean => "boolean",
477            Self::Url => "url",
478        })
479    }
480}
481
482/// A named action with an optional postcondition.
483#[derive(Debug, Clone)]
484pub struct WorkflowStep {
485    pub id: String,
486    pub action: BatchStep,
487    pub intent: Option<WorkflowIntentStep>,
488    pub when: Option<VerificationPredicate>,
489    pub expect: Option<VerificationPredicate>,
490    pub before_retry: Option<VerificationPredicate>,
491    pub transaction: WorkflowTransactionClass,
492    pub idempotency_key: Option<String>,
493    pub max_retries: u32,
494    pub repeat: u32,
495}
496
497/// A semantic workflow action resolved against fresh page evidence at runtime.
498/// Existing locator-based workflow actions remain unchanged.
499#[derive(Debug, Clone, Serialize, Deserialize)]
500#[serde(rename_all = "camelCase", deny_unknown_fields)]
501pub struct WorkflowIntentStep {
502    pub action: SemanticIntentAction,
503    #[serde(default, skip_serializing_if = "Option::is_none")]
504    pub purpose: Option<String>,
505    #[serde(default, skip_serializing_if = "Option::is_none")]
506    pub intent: Option<String>,
507    #[serde(default)]
508    pub scope: IntentScope,
509    #[serde(default)]
510    pub constraints: IntentConstraints,
511    #[serde(default = "default_workflow_resolution_policy")]
512    pub resolution_policy: SemanticResolutionPolicy,
513    #[serde(default, skip_serializing_if = "Option::is_none")]
514    pub value: Option<String>,
515}
516
517impl WorkflowIntentStep {
518    fn validate(&self, path: &str) -> Result<(), WorkflowValidationError> {
519        let supplied = self.purpose.is_some() as u8 + self.intent.is_some() as u8;
520        if supplied != 1 {
521            return Err(WorkflowValidationError::new(
522                format!("{path}.purpose"),
523                "provide exactly one of purpose or intent",
524            ));
525        }
526        if let Some(purpose) = &self.purpose {
527            validate_bytes(
528                &format!("{path}.purpose"),
529                purpose,
530                1,
531                MAX_INTENT_PURPOSE_BYTES,
532            )?;
533        }
534        if let Some(intent) = &self.intent {
535            validate_bytes(
536                &format!("{path}.intent"),
537                intent,
538                1,
539                MAX_INTENT_PURPOSE_BYTES * 2,
540            )?;
541        }
542        if let Some(value) = &self.value {
543            validate_bytes(&format!("{path}.value"), value, 0, 4_096)?;
544        }
545        self.execution_request(path).map(|_| ())
546    }
547
548    fn execution_request(
549        &self,
550        path: &str,
551    ) -> Result<SemanticIntentExecutionRequest, WorkflowValidationError> {
552        let intent = self
553            .intent
554            .clone()
555            .or_else(|| self.purpose.as_deref().map(purpose_to_intent))
556            .ok_or_else(|| {
557                WorkflowValidationError::new(format!("{path}.purpose"), "intent phrase is required")
558            })?;
559        let request = SemanticIntentRequest {
560            schema_version: INTENT_RESOLUTION_SCHEMA_VERSION,
561            intent,
562            action: self.action,
563            scope: self.scope.clone(),
564            constraints: self.constraints.clone(),
565            resolution_policy: self.resolution_policy,
566            expected_revision: None,
567        };
568        let execution = SemanticIntentExecutionRequest {
569            request,
570            candidate_id: "workflow-selected-candidate".into(),
571            value: self.value.clone(),
572        };
573        execution.validate().map_err(|error| {
574            WorkflowValidationError::new(format!("{path}.{}", error.path), error.reason)
575        })?;
576        Ok(execution)
577    }
578}
579
580fn default_workflow_resolution_policy() -> SemanticResolutionPolicy {
581    SemanticResolutionPolicy::RequireUniqueHighConfidence
582}
583
584fn purpose_to_intent(purpose: &str) -> String {
585    let mut result = String::with_capacity(purpose.len() + 8);
586    for (index, character) in purpose.chars().enumerate() {
587        if character.is_ascii_uppercase() && index > 0 {
588            result.push(' ');
589        }
590        result.push(character.to_ascii_lowercase());
591    }
592    result
593}
594
595/// Effect classification used to decide whether a failed attempt may be
596/// replayed before dispatch.
597#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
598#[serde(rename_all = "snake_case")]
599pub enum WorkflowTransactionClass {
600    ReadOnly,
601    Idempotent,
602    ConditionallyIdempotent,
603    NonIdempotent,
604    #[default]
605    Unknown,
606}
607
608impl WorkflowTransactionClass {
609    /// Whether this class permits a retry known to have happened before
610    /// dispatch.
611    pub fn permits_pre_dispatch_retry(self) -> bool {
612        matches!(
613            self,
614            Self::ReadOnly | Self::Idempotent | Self::ConditionallyIdempotent
615        )
616    }
617}
618
619impl Serialize for WorkflowStep {
620    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
621    where
622        S: Serializer,
623    {
624        let mut action = if let Some(intent) = &self.intent {
625            serde_json::json!({ "intent": intent })
626        } else {
627            serde_json::to_value(&self.action).map_err(serde::ser::Error::custom)?
628        };
629        if self.intent.is_none() {
630            let object = action
631                .as_object_mut()
632                .ok_or_else(|| serde::ser::Error::custom("workflow action must be an object"))?;
633            for (internal, public) in [
634                ("timeout_ms", "timeoutMs"),
635                ("include_dom", "includeDom"),
636                ("include_screenshot", "includeScreenshot"),
637                ("include_form_values", "includeFormValues"),
638            ] {
639                if let Some(value) = object.remove(internal) {
640                    object.insert(public.to_string(), value);
641                }
642            }
643        }
644
645        let mut workflow = serde_json::Map::new();
646        workflow.insert("id".into(), Value::String(self.id.clone()));
647        if let Value::Object(action) = action {
648            workflow.extend(action);
649        }
650        if let Some(when) = &self.when {
651            workflow.insert(
652                "when".into(),
653                serde_json::to_value(when).map_err(serde::ser::Error::custom)?,
654            );
655        }
656        if let Some(expect) = &self.expect {
657            workflow.insert(
658                "expect".into(),
659                serde_json::to_value(expect).map_err(serde::ser::Error::custom)?,
660            );
661        }
662        if let Some(before_retry) = &self.before_retry {
663            workflow.insert(
664                "beforeRetry".into(),
665                serde_json::to_value(before_retry).map_err(serde::ser::Error::custom)?,
666            );
667        }
668        workflow.insert(
669            "transaction".into(),
670            serde_json::to_value(self.transaction).map_err(serde::ser::Error::custom)?,
671        );
672        if let Some(key) = &self.idempotency_key {
673            workflow.insert("idempotencyKey".into(), Value::String(key.clone()));
674        }
675        if self.max_retries > 0 {
676            workflow.insert("maxRetries".into(), Value::from(self.max_retries));
677        }
678        if self.repeat > 1 {
679            workflow.insert("repeat".into(), Value::from(self.repeat));
680        }
681        Value::Object(workflow).serialize(serializer)
682    }
683}
684
685impl<'de> Deserialize<'de> for WorkflowStep {
686    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
687    where
688        D: Deserializer<'de>,
689    {
690        let mut workflow = serde_json::Map::<String, Value>::deserialize(deserializer)?;
691        let id = workflow
692            .remove("id")
693            .ok_or_else(|| D::Error::custom("workflow step is missing id"))?;
694        let id = serde_json::from_value(id).map_err(D::Error::custom)?;
695        let when = workflow
696            .remove("when")
697            .map(serde_json::from_value)
698            .transpose()
699            .map_err(D::Error::custom)?;
700        let expect = workflow
701            .remove("expect")
702            .map(serde_json::from_value)
703            .transpose()
704            .map_err(D::Error::custom)?;
705        let before_retry = workflow
706            .remove("beforeRetry")
707            .map(serde_json::from_value)
708            .transpose()
709            .map_err(D::Error::custom)?;
710        let transaction = workflow
711            .remove("transaction")
712            .map(serde_json::from_value)
713            .transpose()
714            .map_err(D::Error::custom)?
715            .unwrap_or_default();
716        let idempotency_key = workflow
717            .remove("idempotencyKey")
718            .map(serde_json::from_value)
719            .transpose()
720            .map_err(D::Error::custom)?;
721        let max_retries = workflow
722            .remove("maxRetries")
723            .map(serde_json::from_value)
724            .transpose()
725            .map_err(D::Error::custom)?
726            .unwrap_or(0);
727        let repeat = workflow
728            .remove("repeat")
729            .map(serde_json::from_value)
730            .transpose()
731            .map_err(D::Error::custom)?
732            .unwrap_or(1);
733        let intent = workflow
734            .remove("intent")
735            .map(serde_json::from_value)
736            .transpose()
737            .map_err(D::Error::custom)?;
738        for (public, internal) in [
739            ("timeoutMs", "timeout_ms"),
740            ("includeDom", "include_dom"),
741            ("includeScreenshot", "include_screenshot"),
742            ("includeFormValues", "include_form_values"),
743        ] {
744            if let Some(value) = workflow.remove(public) {
745                workflow.insert(internal.into(), value);
746            }
747        }
748        let action = if intent.is_some() {
749            BatchStep::Observe {
750                include_dom: false,
751                include_screenshot: false,
752                include_form_values: false,
753            }
754        } else {
755            serde_json::from_value(Value::Object(workflow)).map_err(D::Error::custom)?
756        };
757        Ok(Self {
758            id,
759            action,
760            intent,
761            when,
762            expect,
763            before_retry,
764            transaction,
765            idempotency_key,
766            max_retries,
767            repeat,
768        })
769    }
770}
771
772impl WorkflowStep {
773    fn validate(
774        &self,
775        path: &str,
776        workflow_max_retries: u32,
777    ) -> Result<(), WorkflowValidationError> {
778        validate_name(&format!("{path}.id"), &self.id)?;
779        if let Some(intent) = &self.intent {
780            intent.validate(&format!("{path}.intent"))?;
781        } else {
782            validate_batch_step(&self.action, &format!("{path}.action"))?;
783        }
784        if let Some(predicate) = &self.when {
785            validate_predicate(predicate, &format!("{path}.when"))?;
786        }
787        if let Some(predicate) = &self.expect {
788            validate_predicate(predicate, &format!("{path}.expect"))?;
789        }
790        if let Some(predicate) = &self.before_retry {
791            validate_predicate(predicate, &format!("{path}.beforeRetry"))?;
792        }
793        if let Some(key) = &self.idempotency_key {
794            validate_bytes(&format!("{path}.idempotencyKey"), key, 1, 256)?;
795        }
796        if self.repeat == 0 || self.repeat > MAX_STEP_REPETITIONS {
797            return Err(WorkflowValidationError::new(
798                format!("{path}.repeat"),
799                format!("must be 1..={MAX_STEP_REPETITIONS}"),
800            ));
801        }
802        if self.repeat > 1 && self.when.is_some() {
803            return Err(WorkflowValidationError::new(
804                format!("{path}.repeat"),
805                "conditional steps cannot repeat automatically",
806            ));
807        }
808        if self.repeat > 1 && !self.transaction.permits_pre_dispatch_retry() {
809            return Err(WorkflowValidationError::new(
810                format!("{path}.repeat"),
811                "unknown or non-idempotent steps cannot repeat automatically",
812            ));
813        }
814        if self.max_retries > workflow_max_retries {
815            return Err(WorkflowValidationError::new(
816                format!("{path}.maxRetries"),
817                "step retry count exceeds budgets.maxRetries",
818            ));
819        }
820        match self.transaction {
821            WorkflowTransactionClass::ConditionallyIdempotent if self.idempotency_key.is_none() => {
822                return Err(WorkflowValidationError::new(
823                    format!("{path}.idempotencyKey"),
824                    "conditionally idempotent steps require an idempotency key",
825                ));
826            }
827            WorkflowTransactionClass::NonIdempotent | WorkflowTransactionClass::Unknown
828                if self.max_retries > 0 =>
829            {
830                return Err(WorkflowValidationError::new(
831                    format!("{path}.maxRetries"),
832                    "non-idempotent or unknown steps cannot be retried automatically",
833                ));
834            }
835            _ => {}
836        }
837        Ok(())
838    }
839}
840
841/// Durable state of one workflow step.
842#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
843#[serde(rename_all = "snake_case")]
844pub enum WorkflowStepState {
845    Pending,
846    Ready,
847    Preflight,
848    Resolving,
849    NotDispatched,
850    Dispatched,
851    EffectObserved,
852    Verified,
853    OutputsExtracted,
854    Committed,
855    FailedBeforeDispatch,
856    FailedAfterDispatch,
857    Indeterminate,
858    Skipped,
859}
860
861impl WorkflowStepState {
862    /// Return whether a state transition is valid for the linear runner.
863    pub fn can_transition_to(self, next: Self) -> bool {
864        matches!(
865            (self, next),
866            (Self::Pending, Self::Ready | Self::Skipped)
867                | (Self::Ready, Self::Preflight | Self::Skipped)
868                | (
869                    Self::Preflight,
870                    Self::Resolving | Self::EffectObserved | Self::FailedBeforeDispatch
871                )
872                | (Self::Resolving, Self::NotDispatched | Self::Dispatched)
873                | (Self::NotDispatched, Self::FailedBeforeDispatch)
874                | (
875                    Self::Dispatched,
876                    Self::EffectObserved | Self::FailedAfterDispatch | Self::Indeterminate
877                )
878                | (
879                    Self::EffectObserved,
880                    Self::Verified | Self::FailedAfterDispatch | Self::Indeterminate
881                )
882                | (Self::Verified, Self::OutputsExtracted)
883                | (Self::OutputsExtracted, Self::Committed)
884                | (Self::FailedBeforeDispatch, Self::Ready)
885                | (Self::Committed, Self::Ready)
886        )
887    }
888}
889
890/// The retained state and transition history for one workflow step.
891#[derive(Debug, Clone, Serialize, Deserialize)]
892#[serde(rename_all = "camelCase")]
893pub struct WorkflowStepRecord {
894    pub id: String,
895    pub state: WorkflowStepState,
896    pub history: Vec<WorkflowStepState>,
897    pub attempts: u32,
898    #[serde(default, skip_serializing_if = "Vec::is_empty")]
899    pub execution_ids: Vec<String>,
900    #[serde(default)]
901    pub dispatch_acknowledged: bool,
902    #[serde(default)]
903    pub effect_observed: bool,
904    #[serde(default)]
905    pub postcondition_verified: bool,
906    #[serde(default)]
907    pub retry_safe: bool,
908    #[serde(default, skip_serializing_if = "Option::is_none")]
909    pub previous_revision: Option<u64>,
910    #[serde(default, skip_serializing_if = "Option::is_none")]
911    pub current_revision: Option<u64>,
912    #[serde(skip_serializing_if = "Option::is_none")]
913    pub branch_decision: Option<WorkflowBranchDecision>,
914    #[serde(skip_serializing_if = "Option::is_none")]
915    pub intent_evidence: Option<WorkflowIntentEvidence>,
916    #[serde(skip_serializing_if = "Option::is_none")]
917    pub error: Option<String>,
918}
919
920/// Bounded evidence linking a semantic workflow step to its accepted target.
921#[derive(Debug, Clone, Serialize, Deserialize)]
922#[serde(rename_all = "camelCase")]
923pub struct WorkflowIntentEvidence {
924    pub resolution_id: String,
925    pub candidate_id: String,
926    pub revision: u64,
927    pub resolution: super::SemanticResolution,
928    pub policy_decision: super::IntentPolicyDecision,
929    pub confidence: super::IntentConfidence,
930    pub fingerprint: Option<super::SemanticTargetFingerprint>,
931}
932
933impl WorkflowStepRecord {
934    fn new(id: &str) -> Self {
935        Self {
936            id: id.to_string(),
937            state: WorkflowStepState::Pending,
938            history: vec![WorkflowStepState::Pending],
939            attempts: 0,
940            execution_ids: Vec::new(),
941            dispatch_acknowledged: false,
942            effect_observed: false,
943            postcondition_verified: false,
944            retry_safe: false,
945            previous_revision: None,
946            current_revision: None,
947            branch_decision: None,
948            intent_evidence: None,
949            error: None,
950        }
951    }
952
953    fn transition(&mut self, next: WorkflowStepState) -> Result<(), String> {
954        if !self.state.can_transition_to(next) {
955            return Err(format!(
956                "invalid workflow step transition {} -> {}",
957                state_name(self.state),
958                state_name(next)
959            ));
960        }
961        self.state = next;
962        self.history.push(next);
963        Ok(())
964    }
965
966    fn fail(&mut self, state: WorkflowStepState, error: &str) {
967        let _ = self.transition(state);
968        self.error = Some(bound_workflow_text(error, 512));
969    }
970}
971
972/// Overall outcome of a workflow run.
973#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
974#[serde(rename_all = "snake_case")]
975pub enum WorkflowRunStatus {
976    Completed,
977    Failed,
978    BudgetExhausted,
979    ResumeRequired,
980}
981
982impl WorkflowRunStatus {
983    /// Human-readable label for terminal and TUI surfaces.
984    pub fn label(&self) -> &'static str {
985        match self {
986            Self::Completed => "completed",
987            Self::Failed => "failed",
988            Self::BudgetExhausted => "budget exhausted",
989            Self::ResumeRequired => "resume required",
990        }
991    }
992}
993
994/// Evidence that the workflow's terminal condition was satisfied.
995#[derive(Debug, Clone, Serialize, Deserialize)]
996#[serde(rename_all = "camelCase")]
997pub struct WorkflowTerminalProof {
998    pub predicate: VerificationPredicate,
999    pub revision: u64,
1000    pub state: String,
1001}
1002
1003/// Result of a linear workflow run.
1004#[derive(Debug, Clone, Serialize, Deserialize)]
1005#[serde(rename_all = "camelCase")]
1006pub struct WorkflowRunResult {
1007    pub run_id: String,
1008    pub name: String,
1009    pub workflow_version: String,
1010    pub status: WorkflowRunStatus,
1011    pub steps: Vec<WorkflowStepRecord>,
1012    pub trace: WorkflowTrace,
1013    pub outputs: BTreeMap<String, WorkflowOutput>,
1014    #[serde(skip_serializing_if = "Option::is_none")]
1015    pub terminal_proof: Option<WorkflowTerminalProof>,
1016    #[serde(skip_serializing_if = "Option::is_none")]
1017    pub failed_step: Option<String>,
1018    #[serde(skip_serializing_if = "Option::is_none")]
1019    pub failure: Option<String>,
1020    pub initial_revision: u64,
1021    pub final_revision: u64,
1022}
1023
1024/// Evidence for a declarative step condition evaluated before dispatch.
1025#[derive(Debug, Clone, Serialize, Deserialize)]
1026#[serde(rename_all = "camelCase")]
1027pub struct WorkflowBranchDecision {
1028    pub step_id: String,
1029    pub predicate: VerificationPredicate,
1030    pub matched: bool,
1031}
1032
1033/// Deterministic state-transition trace for replay and debugging.
1034#[derive(Debug, Clone, Serialize, Deserialize)]
1035#[serde(rename_all = "camelCase")]
1036pub struct WorkflowTrace {
1037    #[serde(default = "default_workflow_trace_schema_version")]
1038    pub schema_version: u8,
1039    #[serde(default, skip_serializing_if = "Option::is_none")]
1040    pub run_id: Option<String>,
1041    pub events: Vec<WorkflowTraceEvent>,
1042    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1043    pub branch_decisions: Vec<WorkflowBranchDecision>,
1044    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1045    pub intent_resolutions: Vec<WorkflowIntentEvidence>,
1046}
1047
1048/// One ordered state transition in a workflow trace.
1049#[derive(Debug, Clone, Serialize, Deserialize)]
1050#[serde(rename_all = "camelCase")]
1051pub struct WorkflowTraceEvent {
1052    pub sequence: u64,
1053    pub step_id: String,
1054    pub state: WorkflowStepState,
1055    pub attempt: u32,
1056}
1057
1058impl WorkflowTrace {
1059    /// Build a stable trace from retained step histories.
1060    pub fn from_steps(steps: &[WorkflowStepRecord]) -> Self {
1061        let mut events = Vec::new();
1062        for step in steps {
1063            let mut attempt = 0u32;
1064            for state in &step.history {
1065                if events.len() == MAX_WORKFLOW_TRACE_EVENTS {
1066                    break;
1067                }
1068                if *state == WorkflowStepState::Preflight {
1069                    attempt = attempt.saturating_add(1);
1070                }
1071                events.push(WorkflowTraceEvent {
1072                    sequence: events.len() as u64,
1073                    step_id: step.id.clone(),
1074                    state: *state,
1075                    attempt,
1076                });
1077            }
1078        }
1079        let branch_decisions = steps
1080            .iter()
1081            .filter_map(|step| step.branch_decision.clone())
1082            .collect();
1083        let intent_resolutions = steps
1084            .iter()
1085            .filter_map(|step| step.intent_evidence.clone())
1086            .collect();
1087        Self {
1088            schema_version: WORKFLOW_TRACE_SCHEMA_VERSION,
1089            run_id: None,
1090            events,
1091            branch_decisions,
1092            intent_resolutions,
1093        }
1094    }
1095
1096    /// Validate sequence ordering and the trace event budget.
1097    pub fn validate(&self) -> Result<(), WorkflowValidationError> {
1098        if self.schema_version != WORKFLOW_TRACE_SCHEMA_VERSION {
1099            return Err(WorkflowValidationError::new(
1100                "trace.schemaVersion",
1101                format!(
1102                    "unsupported trace schema version {}; expected {}",
1103                    self.schema_version, WORKFLOW_TRACE_SCHEMA_VERSION
1104                ),
1105            ));
1106        }
1107        if self
1108            .run_id
1109            .as_ref()
1110            .is_some_and(|run_id| run_id.is_empty() || run_id.len() > 128)
1111        {
1112            return Err(WorkflowValidationError::new(
1113                "trace.runId",
1114                "run ID must contain 1 to 128 bytes",
1115            ));
1116        }
1117        if self.events.len() > MAX_WORKFLOW_TRACE_EVENTS {
1118            return Err(WorkflowValidationError::new(
1119                "trace.events",
1120                format!("must contain at most {MAX_WORKFLOW_TRACE_EVENTS} events"),
1121            ));
1122        }
1123        for (index, event) in self.events.iter().enumerate() {
1124            if event.sequence != index as u64 {
1125                return Err(WorkflowValidationError::new(
1126                    format!("trace.events[{index}].sequence"),
1127                    "sequence must be contiguous from zero",
1128                ));
1129            }
1130        }
1131        for (index, decision) in self.branch_decisions.iter().enumerate() {
1132            if decision.step_id.is_empty() {
1133                return Err(WorkflowValidationError::new(
1134                    format!("trace.branchDecisions[{index}].stepId"),
1135                    "step ID must not be empty",
1136                ));
1137            }
1138            validate_predicate(
1139                &decision.predicate,
1140                &format!("trace.branchDecisions[{index}].predicate"),
1141            )?;
1142        }
1143        Ok(())
1144    }
1145
1146    /// Replay the trace into step records without dispatching browser work.
1147    ///
1148    /// Replay is intentionally an inspection operation: it checks that the
1149    /// trace references the declared steps in order, follows the workflow
1150    /// state machine, and carries monotonic attempt numbers. A truncated
1151    /// trace is accepted as a valid prefix when it ends at the event budget.
1152    pub fn replay(
1153        &self,
1154        workflow: &WorkflowDefinition,
1155    ) -> Result<Vec<WorkflowStepRecord>, WorkflowValidationError> {
1156        workflow.validate()?;
1157        self.validate()?;
1158        let mut records: Vec<_> = workflow
1159            .steps
1160            .iter()
1161            .map(|step| WorkflowStepRecord::new(&step.id))
1162            .collect();
1163        let mut seen = vec![false; records.len()];
1164        let mut highest_step = 0usize;
1165        let mut started = false;
1166
1167        for (event_index, event) in self.events.iter().enumerate() {
1168            let step_index = workflow
1169                .steps
1170                .iter()
1171                .position(|step| step.id == event.step_id)
1172                .ok_or_else(|| {
1173                    WorkflowValidationError::new(
1174                        format!("trace.events[{event_index}].stepId"),
1175                        "step ID is not declared by the workflow",
1176                    )
1177                })?;
1178            if !started {
1179                if step_index != 0 {
1180                    return Err(WorkflowValidationError::new(
1181                        format!("trace.events[{event_index}].stepId"),
1182                        "trace must begin with the first declared step",
1183                    ));
1184                }
1185                started = true;
1186            }
1187            if step_index > highest_step.saturating_add(1) {
1188                return Err(WorkflowValidationError::new(
1189                    format!("trace.events[{event_index}].stepId"),
1190                    "trace skips a declared step",
1191                ));
1192            }
1193            if step_index < highest_step {
1194                return Err(WorkflowValidationError::new(
1195                    format!("trace.events[{event_index}].stepId"),
1196                    "trace returns to an earlier step",
1197                ));
1198            }
1199            highest_step = highest_step.max(step_index);
1200
1201            let record = &mut records[step_index];
1202            if !seen[step_index] {
1203                if event.state != WorkflowStepState::Pending || event.attempt != 0 {
1204                    return Err(WorkflowValidationError::new(
1205                        format!("trace.events[{event_index}]"),
1206                        "each step must begin with pending at attempt zero",
1207                    ));
1208                }
1209                seen[step_index] = true;
1210                continue;
1211            }
1212            if event.state == WorkflowStepState::Preflight {
1213                if event.attempt != record.attempts.saturating_add(1) {
1214                    return Err(WorkflowValidationError::new(
1215                        format!("trace.events[{event_index}].attempt"),
1216                        "preflight attempt must increment by one",
1217                    ));
1218                }
1219                record.attempts = event.attempt;
1220            } else if event.attempt != record.attempts {
1221                return Err(WorkflowValidationError::new(
1222                    format!("trace.events[{event_index}].attempt"),
1223                    "event attempt does not match the current step attempt",
1224                ));
1225            }
1226            record.transition(event.state).map_err(|reason| {
1227                WorkflowValidationError::new(format!("trace.events[{event_index}].state"), reason)
1228            })?;
1229        }
1230        for decision in &self.branch_decisions {
1231            let index = workflow
1232                .steps
1233                .iter()
1234                .position(|step| step.id == decision.step_id)
1235                .ok_or_else(|| {
1236                    WorkflowValidationError::new(
1237                        "trace.branchDecisions",
1238                        "branch decision references an undeclared step",
1239                    )
1240                })?;
1241            if workflow.steps[index].when.as_ref() != Some(&decision.predicate) {
1242                return Err(WorkflowValidationError::new(
1243                    "trace.branchDecisions",
1244                    "branch decision predicate does not match the workflow",
1245                ));
1246            }
1247            records[index].branch_decision = Some(decision.clone());
1248        }
1249        Ok(records)
1250    }
1251}
1252
1253fn default_workflow_trace_schema_version() -> u8 {
1254    WORKFLOW_TRACE_SCHEMA_VERSION
1255}
1256
1257impl WorkflowRunResult {
1258    fn failed(
1259        workflow: &WorkflowDefinition,
1260        run_id: String,
1261        steps: Vec<WorkflowStepRecord>,
1262        failed_step: Option<String>,
1263        failure: impl Into<String>,
1264        initial_revision: u64,
1265        final_revision: u64,
1266    ) -> Self {
1267        let mut trace = WorkflowTrace::from_steps(&steps);
1268        trace.run_id = Some(run_id.clone());
1269        Self {
1270            run_id,
1271            name: workflow.name.clone(),
1272            workflow_version: workflow.workflow_version.clone(),
1273            status: WorkflowRunStatus::Failed,
1274            steps,
1275            trace,
1276            outputs: BTreeMap::new(),
1277            terminal_proof: None,
1278            failed_step,
1279            failure: Some(bound_workflow_text(&failure.into(), 512)),
1280            initial_revision,
1281            final_revision,
1282        }
1283    }
1284
1285    fn budget_exhausted(
1286        workflow: &WorkflowDefinition,
1287        run_id: String,
1288        steps: Vec<WorkflowStepRecord>,
1289        failed_step: Option<String>,
1290        reason: impl Into<String>,
1291        initial_revision: u64,
1292        final_revision: u64,
1293    ) -> Self {
1294        let mut trace = WorkflowTrace::from_steps(&steps);
1295        trace.run_id = Some(run_id.clone());
1296        Self {
1297            run_id,
1298            name: workflow.name.clone(),
1299            workflow_version: workflow.workflow_version.clone(),
1300            status: WorkflowRunStatus::BudgetExhausted,
1301            steps,
1302            trace,
1303            outputs: BTreeMap::new(),
1304            terminal_proof: None,
1305            failed_step,
1306            failure: Some(bound_workflow_text(&reason.into(), 512)),
1307            initial_revision,
1308            final_revision,
1309        }
1310    }
1311
1312    fn resume_required(
1313        workflow: &WorkflowDefinition,
1314        run_id: String,
1315        steps: Vec<WorkflowStepRecord>,
1316        failed_step: Option<String>,
1317        reason: impl Into<String>,
1318        initial_revision: u64,
1319        final_revision: u64,
1320    ) -> Self {
1321        let mut trace = WorkflowTrace::from_steps(&steps);
1322        trace.run_id = Some(run_id.clone());
1323        Self {
1324            run_id,
1325            name: workflow.name.clone(),
1326            workflow_version: workflow.workflow_version.clone(),
1327            status: WorkflowRunStatus::ResumeRequired,
1328            steps,
1329            trace,
1330            outputs: BTreeMap::new(),
1331            terminal_proof: None,
1332            failed_step,
1333            failure: Some(bound_workflow_text(&reason.into(), 512)),
1334            initial_revision,
1335            final_revision,
1336        }
1337    }
1338}
1339
1340impl super::BrowserSession {
1341    async fn execute_workflow_intent_step(
1342        &self,
1343        intent: &WorkflowIntentStep,
1344        expected_revision: u64,
1345    ) -> BrowserResult<(super::types::BatchOutcome, WorkflowIntentEvidence)> {
1346        let mut execution = intent.execution_request("workflow.intent")?;
1347        execution.request.expected_revision = Some(expected_revision);
1348        let resolution = self.resolve_intent(&execution.request).await?;
1349        let candidate_id = resolution.selected_candidate.clone().ok_or_else(|| {
1350            format!(
1351                "semantic workflow intent was not uniquely authorized: resolution={}, policy={}",
1352                serde_json::to_string(&resolution.resolution).unwrap_or_else(|_| "unknown".into()),
1353                serde_json::to_string(&resolution.policy_decision)
1354                    .unwrap_or_else(|_| "unknown".into())
1355            )
1356        })?;
1357        execution.candidate_id = candidate_id;
1358        let result = self.execute_intent(&execution).await?;
1359        let accepted_candidate = result
1360            .resolution
1361            .candidates
1362            .iter()
1363            .find(|candidate| candidate.id == result.candidate_id)
1364            .ok_or("executed intent result omitted its accepted candidate")?;
1365        let evidence = WorkflowIntentEvidence {
1366            resolution_id: result.resolution_id.clone(),
1367            candidate_id: result.candidate_id.clone(),
1368            revision: result
1369                .resolution
1370                .revision
1371                .ok_or("executed intent result omitted revision")?,
1372            resolution: result.resolution.resolution,
1373            policy_decision: result.resolution.policy_decision,
1374            confidence: accepted_candidate.confidence,
1375            fingerprint: accepted_candidate.fingerprint.clone(),
1376        };
1377        let Some(action) = result.action else {
1378            return Err(result
1379                .reason
1380                .unwrap_or_else(|| "semantic workflow intent was not executed".into())
1381                .into());
1382        };
1383        let execution_id = action.execution_id.clone();
1384        Ok((
1385            super::types::BatchOutcome {
1386                mode: BatchMode::Fixed,
1387                initial_revision: expected_revision,
1388                final_revision: current_revision(self),
1389                steps: vec![super::types::BatchStepOutcome::Success {
1390                    index: 0,
1391                    action: "intent".into(),
1392                    response_bytes: serde_json::to_string(&action).ok().map(|value| value.len()),
1393                    execution_id: Some(execution_id),
1394                }],
1395                completed: 1,
1396                failed: 0,
1397                total: 1,
1398                success: true,
1399            },
1400            evidence,
1401        ))
1402    }
1403
1404    /// Execute a validated workflow linearly through the existing batch
1405    /// policy and action runtime, retaining bounded per-step evidence.
1406    pub async fn run_workflow(
1407        &self,
1408        workflow: &WorkflowDefinition,
1409        inputs: &BTreeMap<String, Value>,
1410    ) -> BrowserResult<WorkflowRunResult> {
1411        workflow.validate()?;
1412        workflow.validate_inputs(inputs)?;
1413        let resolved_steps = workflow.resolve_actions(inputs)?;
1414        let initial_revision = self
1415            .page_revision
1416            .load(std::sync::atomic::Ordering::Relaxed);
1417        let run_id = format!("run_{}", self.next_execution_id());
1418        let started = Instant::now();
1419        let duration_budget = Duration::from_millis(workflow.budgets.max_duration_ms);
1420        let mut executed_steps = 0u32;
1421        let mut records: Vec<_> = resolved_steps
1422            .iter()
1423            .map(|step| WorkflowStepRecord::new(&step.id))
1424            .collect();
1425
1426        for predicate in &workflow.preconditions {
1427            if workflow_budget_expired(started, duration_budget) {
1428                skip_remaining(&mut records, 0);
1429                return Ok(WorkflowRunResult::budget_exhausted(
1430                    workflow,
1431                    run_id.clone(),
1432                    records,
1433                    None,
1434                    "workflow maxDurationMs budget exhausted before a precondition",
1435                    initial_revision,
1436                    current_revision(self),
1437                ));
1438            }
1439            if let Err(error) = self
1440                .verify(
1441                    predicate.clone(),
1442                    workflow_budget_remaining(started, duration_budget),
1443                )
1444                .await
1445            {
1446                skip_remaining(&mut records, 0);
1447                if workflow_budget_expired(started, duration_budget) {
1448                    return Ok(WorkflowRunResult::budget_exhausted(
1449                        workflow,
1450                        run_id.clone(),
1451                        records,
1452                        None,
1453                        "workflow maxDurationMs budget exhausted while checking a precondition",
1454                        initial_revision,
1455                        current_revision(self),
1456                    ));
1457                }
1458                return Ok(WorkflowRunResult::failed(
1459                    workflow,
1460                    run_id.clone(),
1461                    records,
1462                    None,
1463                    format!("workflow precondition failed: {error}"),
1464                    initial_revision,
1465                    current_revision(self),
1466                ));
1467            }
1468        }
1469
1470        for (index, step) in resolved_steps.iter().enumerate() {
1471            for repetition in 0..step.repeat {
1472                if executed_steps >= workflow.budgets.max_steps
1473                    || workflow_budget_expired(started, duration_budget)
1474                {
1475                    skip_remaining(&mut records, index);
1476                    return Ok(WorkflowRunResult::budget_exhausted(
1477                        workflow,
1478                        run_id.clone(),
1479                        records,
1480                        Some(step.id.clone()),
1481                        if executed_steps >= workflow.budgets.max_steps {
1482                            "workflow maxSteps budget exhausted before dispatch"
1483                        } else {
1484                            "workflow maxDurationMs budget exhausted before dispatch"
1485                        },
1486                        initial_revision,
1487                        current_revision(self),
1488                    ));
1489                }
1490                executed_steps = executed_steps.saturating_add(1);
1491                if repetition > 0 {
1492                    let record = &mut records[index];
1493                    let _ = record.transition(WorkflowStepState::Ready);
1494                }
1495                if let Some(predicate) = &step.when {
1496                    {
1497                        let record = &mut records[index];
1498                        if record.state == WorkflowStepState::Pending {
1499                            let _ = record.transition(WorkflowStepState::Ready);
1500                        }
1501                    }
1502                    match self.evaluate_predicate_once(predicate).await {
1503                        Ok((matched, _state)) => {
1504                            let record = &mut records[index];
1505                            record.branch_decision = Some(WorkflowBranchDecision {
1506                                step_id: step.id.clone(),
1507                                predicate: predicate.clone(),
1508                                matched,
1509                            });
1510                            if !matched {
1511                                let _ = record.transition(WorkflowStepState::Skipped);
1512                                break;
1513                            }
1514                        }
1515                        Err(error) => {
1516                            let message = bound_workflow_text(&error.to_string(), 512);
1517                            let record = &mut records[index];
1518                            let _ = record.transition(WorkflowStepState::Preflight);
1519                            record.fail(WorkflowStepState::FailedBeforeDispatch, &message);
1520                            skip_remaining(&mut records, index + 1);
1521                            if workflow_budget_expired(started, duration_budget) {
1522                                return Ok(WorkflowRunResult::budget_exhausted(
1523                                    workflow,
1524                                    run_id.clone(),
1525                                    records,
1526                                    Some(step.id.clone()),
1527                                    "workflow maxDurationMs budget exhausted while evaluating a branch",
1528                                    initial_revision,
1529                                    current_revision(self),
1530                                ));
1531                            }
1532                            return Ok(WorkflowRunResult::failed(
1533                                workflow,
1534                                run_id.clone(),
1535                                records,
1536                                Some(step.id.clone()),
1537                                message,
1538                                initial_revision,
1539                                current_revision(self),
1540                            ));
1541                        }
1542                    }
1543                }
1544                let mut attempt_number = 0;
1545                let mut effect_marker_completed = false;
1546                let mut intent_evidence = None;
1547                let outcome = loop {
1548                    let attempt_revision = current_revision(self);
1549                    {
1550                        let record = &mut records[index];
1551                        if record.previous_revision.is_none() {
1552                            record.previous_revision = Some(attempt_revision);
1553                        }
1554                        record.retry_safe = step.transaction.permits_pre_dispatch_retry();
1555                        if record.state == WorkflowStepState::Pending {
1556                            let _ = record.transition(WorkflowStepState::Ready);
1557                        }
1558                        let _ = record.transition(WorkflowStepState::Preflight);
1559                        let _ = record.transition(WorkflowStepState::Resolving);
1560                        attempt_number += 1;
1561                        record.attempts = record.attempts.saturating_add(1);
1562                    }
1563
1564                    let outcome = if let Some(intent) = &step.intent {
1565                        match self
1566                            .execute_workflow_intent_step(intent, attempt_revision)
1567                            .await
1568                        {
1569                            Ok((outcome, evidence)) => {
1570                                intent_evidence = Some(evidence);
1571                                Ok(outcome)
1572                            }
1573                            Err(error) => Err(error),
1574                        }
1575                    } else {
1576                        match workflow_target(&step.action) {
1577                            Some(target) => match self.resolve_element(target).await {
1578                                Ok(_) => {
1579                                    self.run_batch_with_mode(
1580                                        std::slice::from_ref(&step.action),
1581                                        false,
1582                                        BatchMode::Unguarded,
1583                                        None,
1584                                    )
1585                                    .await
1586                                }
1587                                Err(error) => Err(error),
1588                            },
1589                            None => {
1590                                self.run_batch_with_mode(
1591                                    std::slice::from_ref(&step.action),
1592                                    false,
1593                                    BatchMode::Unguarded,
1594                                    None,
1595                                )
1596                                .await
1597                            }
1598                        }
1599                    };
1600                    match outcome {
1601                        Ok(outcome) => break outcome,
1602                        Err(error) => {
1603                            let message = bound_workflow_text(&error.to_string(), 512);
1604                            let retry = can_retry_before_dispatch(
1605                                step.transaction,
1606                                false,
1607                                attempt_number,
1608                                step.max_retries,
1609                            );
1610                            {
1611                                let record = &mut records[index];
1612                                record.current_revision = Some(current_revision(self));
1613                                let _ = record.transition(WorkflowStepState::NotDispatched);
1614                                record.fail(WorkflowStepState::FailedBeforeDispatch, &message);
1615                                if retry {
1616                                    let _ = record.transition(WorkflowStepState::Ready);
1617                                }
1618                            }
1619                            if retry {
1620                                let marker_matches = match &step.before_retry {
1621                                    Some(predicate) => {
1622                                        match self.evaluate_predicate_once(predicate).await {
1623                                            Ok((matched, _)) => Some(matched),
1624                                            Err(error) => {
1625                                                let message = bound_workflow_text(
1626                                                    &format!(
1627                                                        "effect marker could not be evaluated: {error}"
1628                                                    ),
1629                                                    512,
1630                                                );
1631                                                let record = &mut records[index];
1632                                                let _ =
1633                                                    record.transition(WorkflowStepState::Preflight);
1634                                                record.fail(
1635                                                    WorkflowStepState::FailedBeforeDispatch,
1636                                                    &message,
1637                                                );
1638                                                skip_remaining(&mut records, index + 1);
1639                                                return Ok(WorkflowRunResult::failed(
1640                                                    workflow,
1641                                                    run_id.clone(),
1642                                                    records,
1643                                                    Some(step.id.clone()),
1644                                                    message,
1645                                                    initial_revision,
1646                                                    current_revision(self),
1647                                                ));
1648                                            }
1649                                        }
1650                                    }
1651                                    None => None,
1652                                };
1653                                if marker_matches == Some(true) {
1654                                    effect_marker_completed = true;
1655                                    break super::types::BatchOutcome {
1656                                        mode: BatchMode::Unguarded,
1657                                        initial_revision: current_revision(self),
1658                                        final_revision: current_revision(self),
1659                                        steps: Vec::new(),
1660                                        completed: 0,
1661                                        failed: 0,
1662                                        total: 0,
1663                                        success: true,
1664                                    };
1665                                }
1666                                continue;
1667                            }
1668                            let message = records[index]
1669                                .error
1670                                .clone()
1671                                .unwrap_or_else(|| "workflow step failed".into());
1672                            skip_remaining(&mut records, index + 1);
1673                            return Ok(WorkflowRunResult::failed(
1674                                workflow,
1675                                run_id.clone(),
1676                                records,
1677                                Some(step.id.clone()),
1678                                message,
1679                                initial_revision,
1680                                current_revision(self),
1681                            ));
1682                        }
1683                    }
1684                };
1685
1686                if effect_marker_completed {
1687                    commit_workflow_effect_marker(&mut records[index], current_revision(self));
1688                    continue;
1689                }
1690
1691                if !outcome.success {
1692                    let message = outcome
1693                        .steps
1694                        .last()
1695                        .and_then(|step| match step {
1696                            super::types::BatchStepOutcome::Error { message, .. } => {
1697                                Some(message.as_str())
1698                            }
1699                            super::types::BatchStepOutcome::Success { .. } => None,
1700                        })
1701                        .unwrap_or("workflow action failed after dispatch");
1702                    let message = {
1703                        let record = &mut records[index];
1704                        record.dispatch_acknowledged = true;
1705                        record.current_revision = Some(current_revision(self));
1706                        let _ = record.transition(WorkflowStepState::Dispatched);
1707                        record.fail(WorkflowStepState::Indeterminate, message);
1708                        record
1709                            .error
1710                            .clone()
1711                            .unwrap_or_else(|| "workflow step failed".into())
1712                    };
1713                    skip_remaining(&mut records, index + 1);
1714                    return Ok(WorkflowRunResult::resume_required(
1715                        workflow,
1716                        run_id.clone(),
1717                        records,
1718                        Some(step.id.clone()),
1719                        message,
1720                        initial_revision,
1721                        current_revision(self),
1722                    ));
1723                }
1724
1725                {
1726                    records[index].intent_evidence = intent_evidence;
1727                    for execution_id in outcome.steps.iter().filter_map(|step| match step {
1728                        super::types::BatchStepOutcome::Success {
1729                            execution_id: Some(execution_id),
1730                            ..
1731                        } => Some(execution_id.clone()),
1732                        _ => None,
1733                    }) {
1734                        records[index].execution_ids.push(execution_id);
1735                    }
1736                    let record = &mut records[index];
1737                    record.dispatch_acknowledged = true;
1738                    record.effect_observed = true;
1739                    record.current_revision = Some(current_revision(self));
1740                    let _ = record.transition(WorkflowStepState::Dispatched);
1741                    let _ = record.transition(WorkflowStepState::EffectObserved);
1742                }
1743                if let Some(predicate) = &step.expect
1744                    && let Err(error) = self
1745                        .verify(
1746                            predicate.clone(),
1747                            workflow_budget_remaining(started, duration_budget),
1748                        )
1749                        .await
1750                {
1751                    let message = {
1752                        let record = &mut records[index];
1753                        record.current_revision = Some(current_revision(self));
1754                        record.fail(WorkflowStepState::FailedAfterDispatch, &error.to_string());
1755                        record
1756                            .error
1757                            .clone()
1758                            .unwrap_or_else(|| "workflow verification failed".into())
1759                    };
1760                    skip_remaining(&mut records, index + 1);
1761                    if workflow_budget_expired(started, duration_budget) {
1762                        return Ok(WorkflowRunResult::budget_exhausted(
1763                            workflow,
1764                            run_id.clone(),
1765                            records,
1766                            Some(step.id.clone()),
1767                            "workflow maxDurationMs budget exhausted while verifying a step",
1768                            initial_revision,
1769                            current_revision(self),
1770                        ));
1771                    }
1772                    return Ok(WorkflowRunResult::resume_required(
1773                        workflow,
1774                        run_id.clone(),
1775                        records,
1776                        Some(step.id.clone()),
1777                        message,
1778                        initial_revision,
1779                        current_revision(self),
1780                    ));
1781                }
1782                let record = &mut records[index];
1783                record.postcondition_verified = true;
1784                let _ = record.transition(WorkflowStepState::Verified);
1785                let _ = record.transition(WorkflowStepState::OutputsExtracted);
1786                let _ = record.transition(WorkflowStepState::Committed);
1787            }
1788        }
1789
1790        if workflow_budget_expired(started, duration_budget) {
1791            return Ok(WorkflowRunResult::budget_exhausted(
1792                workflow,
1793                run_id.clone(),
1794                records,
1795                None,
1796                "workflow maxDurationMs budget exhausted before terminal verification",
1797                initial_revision,
1798                current_revision(self),
1799            ));
1800        }
1801        let terminal_proof = match self
1802            .verify(
1803                workflow.terminal_condition.clone(),
1804                workflow_budget_remaining(started, duration_budget),
1805            )
1806            .await
1807        {
1808            Ok(outcome) => WorkflowTerminalProof {
1809                predicate: outcome.predicate,
1810                revision: current_revision(self),
1811                state: outcome.state,
1812            },
1813            Err(error) => {
1814                if workflow_budget_expired(started, duration_budget) {
1815                    return Ok(WorkflowRunResult::budget_exhausted(
1816                        workflow,
1817                        run_id.clone(),
1818                        records,
1819                        None,
1820                        "workflow maxDurationMs budget exhausted while verifying the terminal condition",
1821                        initial_revision,
1822                        current_revision(self),
1823                    ));
1824                }
1825                return Ok(WorkflowRunResult::failed(
1826                    workflow,
1827                    run_id.clone(),
1828                    records,
1829                    None,
1830                    format!("workflow terminal condition was not proven: {error}"),
1831                    initial_revision,
1832                    current_revision(self),
1833                ));
1834            }
1835        };
1836        if workflow_budget_expired(started, duration_budget) {
1837            return Ok(WorkflowRunResult::budget_exhausted(
1838                workflow,
1839                run_id.clone(),
1840                records,
1841                None,
1842                "workflow maxDurationMs budget exhausted before output extraction",
1843                initial_revision,
1844                current_revision(self),
1845            ));
1846        }
1847        let outputs = match extract_workflow_outputs(self, workflow).await {
1848            Ok(outputs) => outputs,
1849            Err(error) => {
1850                if workflow_budget_expired(started, duration_budget) {
1851                    return Ok(WorkflowRunResult::budget_exhausted(
1852                        workflow,
1853                        run_id.clone(),
1854                        records,
1855                        None,
1856                        "workflow maxDurationMs budget exhausted while extracting outputs",
1857                        initial_revision,
1858                        current_revision(self),
1859                    ));
1860                }
1861                return Ok(WorkflowRunResult::failed(
1862                    workflow,
1863                    run_id.clone(),
1864                    records,
1865                    None,
1866                    format!("workflow output extraction failed: {error}"),
1867                    initial_revision,
1868                    current_revision(self),
1869                ));
1870            }
1871        };
1872        if workflow_budget_expired(started, duration_budget) {
1873            return Ok(WorkflowRunResult::budget_exhausted(
1874                workflow,
1875                run_id.clone(),
1876                records,
1877                None,
1878                "workflow maxDurationMs budget exhausted after output extraction",
1879                initial_revision,
1880                current_revision(self),
1881            ));
1882        }
1883
1884        let mut trace = WorkflowTrace::from_steps(&records);
1885        trace.run_id = Some(run_id.clone());
1886        Ok(WorkflowRunResult {
1887            run_id,
1888            name: workflow.name.clone(),
1889            workflow_version: workflow.workflow_version.clone(),
1890            status: WorkflowRunStatus::Completed,
1891            steps: records,
1892            trace,
1893            outputs,
1894            terminal_proof: Some(terminal_proof),
1895            failed_step: None,
1896            failure: None,
1897            initial_revision,
1898            final_revision: current_revision(self),
1899        })
1900    }
1901}
1902
1903impl super::BrowserSession {
1904    /// Export a deterministic, redacted workflow checkpoint bounded to 8 KiB.
1905    pub async fn export_workflow_checkpoint(
1906        &self,
1907        workflow: &WorkflowDefinition,
1908        result: &WorkflowRunResult,
1909    ) -> BrowserResult<WorkflowCheckpoint> {
1910        workflow.validate()?;
1911        if result.name != workflow.name
1912            || result.workflow_version != workflow.workflow_version
1913            || result.steps.len() != workflow.steps.len()
1914        {
1915            return Err(WorkflowResumeError::CheckpointShape(
1916                "run result does not belong to workflow definition".into(),
1917            )
1918            .into());
1919        }
1920        let page = self.page_info().await?;
1921        let next_step_index = result
1922            .steps
1923            .iter()
1924            .position(|step| step.state != WorkflowStepState::Committed)
1925            .unwrap_or(result.steps.len());
1926        let checkpoint = WorkflowCheckpoint {
1927            schema_version: WORKFLOW_CHECKPOINT_SCHEMA_VERSION,
1928            run_id: result.run_id.clone(),
1929            workflow_name: workflow.name.clone(),
1930            workflow_version: workflow.workflow_version.clone(),
1931            definition_hash: workflow_definition_hash(workflow)?,
1932            status: result.status,
1933            next_step_index,
1934            steps: result
1935                .steps
1936                .iter()
1937                .map(|step| WorkflowCheckpointStep {
1938                    id: step.id.clone(),
1939                    state: step.state,
1940                    attempts: step.attempts,
1941                    history: step.history.clone(),
1942                    execution_ids: step.execution_ids.clone(),
1943                    dispatch_acknowledged: step.dispatch_acknowledged,
1944                    effect_observed: step.effect_observed,
1945                    postcondition_verified: step.postcondition_verified,
1946                    retry_safe: step.retry_safe,
1947                    previous_revision: step.previous_revision,
1948                    current_revision: step.current_revision,
1949                    branch_decision: step.branch_decision.clone(),
1950                    intent_evidence: step.intent_evidence.clone(),
1951                })
1952                .collect(),
1953            page: WorkflowCheckpointPage {
1954                target_id: bound_workflow_text(&page.target_id, 256),
1955                frame_id: bound_workflow_text(&page.frame_id, 256),
1956                url: bound_workflow_text(&page.url, 1_024),
1957                title: bound_workflow_text(&page.title, 1_024),
1958                revision: current_revision(self),
1959            },
1960        };
1961        checkpoint.validate_size()?;
1962        Ok(checkpoint)
1963    }
1964
1965    /// Parse and validate a workflow checkpoint without contacting Chrome.
1966    pub fn parse_workflow_checkpoint(
1967        input: &str,
1968    ) -> Result<WorkflowCheckpoint, WorkflowResumeError> {
1969        let checkpoint: WorkflowCheckpoint = serde_json::from_str(input)
1970            .map_err(|error| WorkflowResumeError::CheckpointShape(error.to_string()))?;
1971        checkpoint.validate_size()?;
1972        Ok(checkpoint)
1973    }
1974
1975    /// Reconcile a checkpoint with the current route and return the only safe
1976    /// next step. This method never dispatches a browser action.
1977    pub async fn reconcile_workflow_checkpoint(
1978        &self,
1979        workflow: &WorkflowDefinition,
1980        checkpoint: &WorkflowCheckpoint,
1981    ) -> BrowserResult<WorkflowResumePlan> {
1982        workflow.validate()?;
1983        checkpoint.validate_size()?;
1984        if checkpoint.schema_version != WORKFLOW_CHECKPOINT_SCHEMA_VERSION {
1985            return Err(WorkflowResumeError::SchemaVersionMismatch {
1986                expected: WORKFLOW_CHECKPOINT_SCHEMA_VERSION,
1987                found: checkpoint.schema_version,
1988            }
1989            .into());
1990        }
1991        if checkpoint.workflow_name != workflow.name
1992            || checkpoint.workflow_version != workflow.workflow_version
1993            || checkpoint.definition_hash != workflow_definition_hash(workflow)?
1994        {
1995            return Err(WorkflowResumeError::DefinitionMismatch.into());
1996        }
1997        if checkpoint.steps.len() != workflow.steps.len()
1998            || checkpoint
1999                .steps
2000                .iter()
2001                .zip(&workflow.steps)
2002                .any(|(checkpoint_step, step)| checkpoint_step.id != step.id)
2003        {
2004            return Err(WorkflowResumeError::CheckpointShape(
2005                "checkpoint steps do not match workflow steps".into(),
2006            )
2007            .into());
2008        }
2009
2010        let page = self.page_info().await?;
2011        if checkpoint.page.target_id != page.target_id
2012            || checkpoint.page.frame_id != page.frame_id
2013            || checkpoint.page.url != bound_workflow_text(&page.url, 1_024)
2014            || checkpoint.page.title != bound_workflow_text(&page.title, 1_024)
2015        {
2016            return Err(WorkflowResumeError::RouteChanged.into());
2017        }
2018
2019        let mut next_step_index = checkpoint.steps.len();
2020        for (index, checkpoint_step) in checkpoint.steps.iter().enumerate() {
2021            if checkpoint_step.state != WorkflowStepState::Committed {
2022                next_step_index = index;
2023                break;
2024            }
2025        }
2026        if checkpoint.next_step_index != next_step_index {
2027            return Err(WorkflowResumeError::CheckpointShape(
2028                "nextStepIndex does not match step states".into(),
2029            )
2030            .into());
2031        }
2032        if checkpoint.status == WorkflowRunStatus::Completed
2033            && next_step_index != workflow.steps.len()
2034        {
2035            return Err(WorkflowResumeError::CheckpointShape(
2036                "completed checkpoint has uncommitted steps".into(),
2037            )
2038            .into());
2039        }
2040        if next_step_index < workflow.steps.len() {
2041            let step = &workflow.steps[next_step_index];
2042            let state = checkpoint.steps[next_step_index].state;
2043            if state == WorkflowStepState::FailedBeforeDispatch
2044                && !step.transaction.permits_pre_dispatch_retry()
2045            {
2046                return Err(WorkflowResumeError::InvalidState {
2047                    step_id: step.id.clone(),
2048                    state,
2049                }
2050                .into());
2051            }
2052            if !matches!(
2053                state,
2054                WorkflowStepState::Pending | WorkflowStepState::FailedBeforeDispatch
2055            ) {
2056                return Err(WorkflowResumeError::InvalidState {
2057                    step_id: step.id.clone(),
2058                    state,
2059                }
2060                .into());
2061            }
2062            for checkpoint_step in checkpoint.steps.iter().skip(next_step_index + 1) {
2063                if checkpoint_step.state != WorkflowStepState::Skipped {
2064                    return Err(WorkflowResumeError::InvalidState {
2065                        step_id: checkpoint_step.id.clone(),
2066                        state: checkpoint_step.state,
2067                    }
2068                    .into());
2069                }
2070            }
2071        }
2072
2073        Ok(WorkflowResumePlan {
2074            workflow_name: workflow.name.clone(),
2075            workflow_version: workflow.workflow_version.clone(),
2076            next_step_index,
2077            current_revision: current_revision(self),
2078            reconciled: true,
2079        })
2080    }
2081
2082    /// Reconcile a checkpoint and execute only its safe pending suffix.
2083    /// Previously committed steps are never re-dispatched by this method.
2084    pub async fn resume_workflow(
2085        &self,
2086        workflow: &WorkflowDefinition,
2087        inputs: &BTreeMap<String, Value>,
2088        checkpoint: &WorkflowCheckpoint,
2089    ) -> BrowserResult<WorkflowRunResult> {
2090        let plan = self
2091            .reconcile_workflow_checkpoint(workflow, checkpoint)
2092            .await?;
2093        if plan.next_step_index >= workflow.steps.len() {
2094            return Err(WorkflowResumeError::CheckpointShape(
2095                "workflow checkpoint is already complete".into(),
2096            )
2097            .into());
2098        }
2099        let mut suffix = workflow.clone();
2100        suffix.steps = workflow.steps[plan.next_step_index..].to_vec();
2101        let mut result = Box::pin(self.run_workflow(&suffix, inputs)).await?;
2102        let mut prefix = checkpoint.steps[..plan.next_step_index]
2103            .iter()
2104            .map(checkpoint_step_to_record)
2105            .collect::<Vec<_>>();
2106        prefix.append(&mut result.steps);
2107        result.steps = prefix;
2108        result.trace = WorkflowTrace::from_steps(&result.steps);
2109        result.trace.run_id = Some(result.run_id.clone());
2110        Ok(result)
2111    }
2112}
2113
2114fn checkpoint_step_to_record(step: &WorkflowCheckpointStep) -> WorkflowStepRecord {
2115    let history = if step.history.is_empty() {
2116        vec![
2117            WorkflowStepState::Pending,
2118            WorkflowStepState::Ready,
2119            WorkflowStepState::Preflight,
2120            WorkflowStepState::Resolving,
2121            WorkflowStepState::Dispatched,
2122            WorkflowStepState::EffectObserved,
2123            WorkflowStepState::Verified,
2124            WorkflowStepState::OutputsExtracted,
2125            WorkflowStepState::Committed,
2126        ]
2127    } else {
2128        step.history.clone()
2129    };
2130    WorkflowStepRecord {
2131        id: step.id.clone(),
2132        state: step.state,
2133        history,
2134        attempts: step.attempts,
2135        execution_ids: step.execution_ids.clone(),
2136        dispatch_acknowledged: step.dispatch_acknowledged,
2137        effect_observed: step.effect_observed,
2138        postcondition_verified: step.postcondition_verified,
2139        retry_safe: step.retry_safe,
2140        previous_revision: step.previous_revision,
2141        current_revision: step.current_revision,
2142        branch_decision: step.branch_decision.clone(),
2143        intent_evidence: step.intent_evidence.clone(),
2144        error: None,
2145    }
2146}
2147
2148impl WorkflowCheckpoint {
2149    /// Serialize a checkpoint after enforcing its size and schema bounds.
2150    pub fn to_canonical_json(&self) -> Result<String, WorkflowResumeError> {
2151        self.validate_size()?;
2152        serde_json::to_string(self)
2153            .map_err(|error| WorkflowResumeError::CheckpointShape(error.to_string()))
2154    }
2155
2156    fn validate_size(&self) -> Result<(), WorkflowResumeError> {
2157        if self.schema_version != WORKFLOW_CHECKPOINT_SCHEMA_VERSION {
2158            return Err(WorkflowResumeError::SchemaVersionMismatch {
2159                expected: WORKFLOW_CHECKPOINT_SCHEMA_VERSION,
2160                found: self.schema_version,
2161            });
2162        }
2163        if self.steps.len() > MAX_STEPS {
2164            return Err(WorkflowResumeError::CheckpointShape(
2165                "checkpoint contains too many steps".into(),
2166            ));
2167        }
2168        if self.run_id.len() > 128 {
2169            return Err(WorkflowResumeError::CheckpointShape(
2170                "checkpoint runId is too long".into(),
2171            ));
2172        }
2173        for (index, step) in self.steps.iter().enumerate() {
2174            if step.history.len() > MAX_CHECKPOINT_HISTORY_STATES {
2175                return Err(WorkflowResumeError::CheckpointShape(format!(
2176                    "checkpoint step {index} contains too much state history"
2177                )));
2178            }
2179            if !step.history.is_empty() && step.history.last() != Some(&step.state) {
2180                return Err(WorkflowResumeError::CheckpointShape(format!(
2181                    "checkpoint step {index} history does not end at its state"
2182                )));
2183            }
2184            if step.execution_ids.len() > MAX_CHECKPOINT_EXECUTION_IDS
2185                || step.execution_ids.iter().any(|id| id.len() > 128)
2186            {
2187                return Err(WorkflowResumeError::CheckpointShape(format!(
2188                    "checkpoint step {index} contains too many execution IDs"
2189                )));
2190            }
2191        }
2192        let bytes = serde_json::to_vec(self)
2193            .map_err(|error| WorkflowResumeError::CheckpointShape(error.to_string()))?;
2194        if bytes.len() > MAX_WORKFLOW_CHECKPOINT_BYTES {
2195            return Err(WorkflowResumeError::CheckpointTooLarge);
2196        }
2197        Ok(())
2198    }
2199}
2200
2201fn workflow_definition_hash(
2202    workflow: &WorkflowDefinition,
2203) -> Result<String, WorkflowValidationError> {
2204    let canonical = workflow.to_canonical_json()?;
2205    let digest = Sha256::digest(canonical.as_bytes());
2206    Ok(digest.iter().map(|byte| format!("{byte:02x}")).collect())
2207}
2208
2209fn workflow_target(action: &BatchStep) -> Option<&str> {
2210    match action {
2211        BatchStep::Click { target }
2212        | BatchStep::Check { target }
2213        | BatchStep::Uncheck { target }
2214        | BatchStep::Select { target, .. }
2215        | BatchStep::Clear { target } => Some(target),
2216        BatchStep::Type { target, .. } => target.as_deref(),
2217        _ => None,
2218    }
2219}
2220
2221fn resolve_workflow_intent(
2222    intent: &WorkflowIntentStep,
2223    inputs: &BTreeMap<String, Value>,
2224    path: &str,
2225) -> Result<WorkflowIntentStep, WorkflowValidationError> {
2226    let resolve = |field: &str, value: &str, maximum: usize| {
2227        resolve_input_template(value, inputs, &format!("{path}.{field}"), maximum)
2228    };
2229    let resolve_optional = |field: &str, value: &Option<String>, maximum: usize| {
2230        value
2231            .as_deref()
2232            .map(|value| resolve(field, value, maximum))
2233            .transpose()
2234    };
2235    let mut resolved = intent.clone();
2236    resolved.purpose = resolve_optional("purpose", &intent.purpose, MAX_INTENT_PURPOSE_BYTES)?;
2237    resolved.intent = resolve_optional("intent", &intent.intent, MAX_INTENT_PURPOSE_BYTES * 2)?;
2238    resolved.value = resolve_optional("value", &intent.value, 4_096)?;
2239    resolved.scope.region_id = resolve_optional("scope.regionId", &intent.scope.region_id, 128)?;
2240    resolved.scope.form_label = resolve_optional("scope.formLabel", &intent.scope.form_label, 256)?;
2241    resolved.constraints.role = resolve_optional("constraints.role", &intent.constraints.role, 64)?;
2242    resolved.constraints.name = resolve_optional(
2243        "constraints.name",
2244        &intent.constraints.name,
2245        MAX_TARGET_BYTES,
2246    )?;
2247    resolved.constraints.name_contains = resolve_optional(
2248        "constraints.nameContains",
2249        &intent.constraints.name_contains,
2250        MAX_TARGET_BYTES,
2251    )?;
2252    resolved.constraints.exclude_text = intent
2253        .constraints
2254        .exclude_text
2255        .iter()
2256        .enumerate()
2257        .map(|(index, value)| {
2258            resolve_input_template(
2259                value,
2260                inputs,
2261                &format!("{path}.constraints.excludeText[{index}]"),
2262                MAX_TARGET_BYTES,
2263            )
2264        })
2265        .collect::<Result<_, _>>()?;
2266    resolved.validate(path)?;
2267    Ok(resolved)
2268}
2269
2270fn resolve_batch_step(
2271    action: &BatchStep,
2272    inputs: &BTreeMap<String, Value>,
2273    path: &str,
2274) -> Result<BatchStep, WorkflowValidationError> {
2275    let resolve = |field: &str, value: &str, maximum: usize| {
2276        resolve_input_template(value, inputs, &format!("{path}.{field}"), maximum)
2277    };
2278    Ok(match action {
2279        BatchStep::Navigate { url, timeout_ms } => BatchStep::Navigate {
2280            url: resolve("url", url, MAX_TARGET_BYTES)?,
2281            timeout_ms: *timeout_ms,
2282        },
2283        BatchStep::Click { target } => BatchStep::Click {
2284            target: resolve("target", target, MAX_TARGET_BYTES)?,
2285        },
2286        BatchStep::Type { text, target } => BatchStep::Type {
2287            text: resolve("text", text, MAX_TEXT_BYTES)?,
2288            target: target
2289                .as_deref()
2290                .map(|value| resolve("target", value, MAX_TARGET_BYTES))
2291                .transpose()?,
2292        },
2293        BatchStep::Check { target } => BatchStep::Check {
2294            target: resolve("target", target, MAX_TARGET_BYTES)?,
2295        },
2296        BatchStep::Uncheck { target } => BatchStep::Uncheck {
2297            target: resolve("target", target, MAX_TARGET_BYTES)?,
2298        },
2299        BatchStep::Select { target, value } => BatchStep::Select {
2300            target: resolve("target", target, MAX_TARGET_BYTES)?,
2301            value: resolve("value", value, MAX_TEXT_BYTES)?,
2302        },
2303        BatchStep::Clear { target } => BatchStep::Clear {
2304            target: resolve("target", target, MAX_TARGET_BYTES)?,
2305        },
2306        BatchStep::Wait {
2307            condition,
2308            timeout_ms,
2309        } => BatchStep::Wait {
2310            condition: resolve("condition", condition, MAX_WAIT_CONDITION_BYTES)?,
2311            timeout_ms: *timeout_ms,
2312        },
2313        BatchStep::Scroll { dx, dy } => BatchStep::Scroll { dx: *dx, dy: *dy },
2314        BatchStep::Observe {
2315            include_dom,
2316            include_screenshot,
2317            include_form_values,
2318        } => BatchStep::Observe {
2319            include_dom: *include_dom,
2320            include_screenshot: *include_screenshot,
2321            include_form_values: *include_form_values,
2322        },
2323        BatchStep::Screenshot => BatchStep::Screenshot,
2324        BatchStep::Evaluate { expression } => BatchStep::Evaluate {
2325            expression: resolve("expression", expression, MAX_TEXT_BYTES)?,
2326        },
2327        BatchStep::AcceptDialog => BatchStep::AcceptDialog,
2328        BatchStep::DismissDialog => BatchStep::DismissDialog,
2329    })
2330}
2331
2332fn resolve_input_template(
2333    value: &str,
2334    inputs: &BTreeMap<String, Value>,
2335    path: &str,
2336    maximum: usize,
2337) -> Result<String, WorkflowValidationError> {
2338    let marker = "${inputs.";
2339    let mut resolved = String::with_capacity(value.len());
2340    let mut remainder = value;
2341    while let Some(start) = remainder.find(marker) {
2342        resolved.push_str(&remainder[..start]);
2343        let placeholder = &remainder[start..];
2344        let end = placeholder.find('}').ok_or_else(|| {
2345            WorkflowValidationError::new(path, "input placeholder is missing a closing brace")
2346        })?;
2347        let name = &placeholder[marker.len()..end];
2348        if name.is_empty() || name.contains(['{', '}', '$']) {
2349            return Err(WorkflowValidationError::new(
2350                path,
2351                "input placeholder name is invalid",
2352            ));
2353        }
2354        let input = inputs.get(name).ok_or_else(|| {
2355            WorkflowValidationError::new(path, format!("input {name:?} is missing or not declared"))
2356        })?;
2357        let text = match input {
2358            Value::String(text) => text.clone(),
2359            Value::Bool(value) => value.to_string(),
2360            Value::Number(value) => value.to_string(),
2361            _ => {
2362                return Err(WorkflowValidationError::new(
2363                    path,
2364                    format!("input {name:?} cannot be inserted into an action string"),
2365                ));
2366            }
2367        };
2368        resolved.push_str(&text);
2369        remainder = &placeholder[end + 1..];
2370    }
2371    resolved.push_str(remainder);
2372    validate_bytes(path, &resolved, 0, maximum)?;
2373    Ok(resolved)
2374}
2375
2376async fn extract_workflow_outputs(
2377    session: &super::BrowserSession,
2378    workflow: &WorkflowDefinition,
2379) -> BrowserResult<BTreeMap<String, WorkflowOutput>> {
2380    let page = if workflow
2381        .outputs
2382        .values()
2383        .any(|output| !matches!(output.source, WorkflowOutputSource::VisibleText))
2384    {
2385        Some(session.page_info().await?)
2386    } else {
2387        None
2388    };
2389    let visible_text = if workflow
2390        .outputs
2391        .values()
2392        .any(|output| matches!(output.source, WorkflowOutputSource::VisibleText))
2393    {
2394        Some(session.text().await?)
2395    } else {
2396        None
2397    };
2398    let mut outputs = BTreeMap::new();
2399    let mut extracted_bytes = 0usize;
2400    let revision = current_revision(session);
2401    for (name, declaration) in &workflow.outputs {
2402        let text = match declaration.source {
2403            WorkflowOutputSource::PageUrl => page.as_ref().map(|page| page.url.as_str()),
2404            WorkflowOutputSource::PageTitle => page.as_ref().map(|page| page.title.as_str()),
2405            WorkflowOutputSource::VisibleText => visible_text.as_deref(),
2406        }
2407        .ok_or_else(|| format!("output {name:?} has no extraction source"))?;
2408        extracted_bytes = extracted_bytes.saturating_add(text.len());
2409        if extracted_bytes > workflow.budgets.max_extracted_bytes {
2410            return Err(format!(
2411                "outputs exceed maxExtractedBytes {}",
2412                workflow.budgets.max_extracted_bytes
2413            )
2414            .into());
2415        }
2416        let value = typed_output_value(name, declaration.value_type, text)?;
2417        let redacted = declaration.sensitive;
2418        outputs.insert(
2419            name.clone(),
2420            WorkflowOutput {
2421                value_type: declaration.value_type,
2422                value: if redacted { Value::Null } else { value },
2423                redacted,
2424                evidence: WorkflowOutputEvidence {
2425                    source: declaration.source,
2426                    revision,
2427                },
2428            },
2429        );
2430    }
2431    Ok(outputs)
2432}
2433
2434fn typed_output_value(
2435    name: &str,
2436    value_type: WorkflowValueType,
2437    text: &str,
2438) -> BrowserResult<Value> {
2439    let trimmed = text.trim();
2440    match value_type {
2441        WorkflowValueType::String => Ok(Value::String(text.to_string())),
2442        WorkflowValueType::Url => {
2443            if Url::parse(trimmed).is_err() {
2444                return Err(format!("output {name:?} is not a valid URL").into());
2445            }
2446            Ok(Value::String(text.to_string()))
2447        }
2448        WorkflowValueType::Integer => trimmed
2449            .parse::<i64>()
2450            .map(Value::from)
2451            .map_err(|_| format!("output {name:?} cannot be parsed as an integer").into()),
2452        WorkflowValueType::Number => {
2453            let number = trimmed
2454                .parse::<f64>()
2455                .map_err(|_| format!("output {name:?} cannot be parsed as a number"))?;
2456            serde_json::Number::from_f64(number)
2457                .map(Value::Number)
2458                .ok_or_else(|| format!("output {name:?} is not a finite number").into())
2459        }
2460        WorkflowValueType::Boolean => match trimmed {
2461            "true" => Ok(Value::Bool(true)),
2462            "false" => Ok(Value::Bool(false)),
2463            _ => Err(format!("output {name:?} cannot be parsed as a boolean").into()),
2464        },
2465    }
2466}
2467
2468fn current_revision(session: &super::BrowserSession) -> u64 {
2469    session
2470        .page_revision
2471        .load(std::sync::atomic::Ordering::Relaxed)
2472}
2473
2474fn workflow_budget_expired(started: Instant, budget: Duration) -> bool {
2475    started.elapsed() >= budget
2476}
2477
2478fn workflow_budget_remaining(started: Instant, budget: Duration) -> Duration {
2479    budget.saturating_sub(started.elapsed())
2480}
2481
2482fn can_retry_before_dispatch(
2483    transaction: WorkflowTransactionClass,
2484    dispatch_observed: bool,
2485    attempt_number: u32,
2486    max_retries: u32,
2487) -> bool {
2488    !dispatch_observed && attempt_number <= max_retries && transaction.permits_pre_dispatch_retry()
2489}
2490
2491fn skip_remaining(records: &mut [WorkflowStepRecord], start: usize) {
2492    for record in records.iter_mut().skip(start) {
2493        if record.state == WorkflowStepState::Pending {
2494            let _ = record.transition(WorkflowStepState::Skipped);
2495        }
2496    }
2497}
2498
2499fn commit_workflow_effect_marker(record: &mut WorkflowStepRecord, revision: u64) {
2500    if record.state == WorkflowStepState::Ready {
2501        let _ = record.transition(WorkflowStepState::Preflight);
2502    }
2503    if record.state == WorkflowStepState::Preflight {
2504        let _ = record.transition(WorkflowStepState::EffectObserved);
2505    }
2506    record.effect_observed = true;
2507    record.postcondition_verified = true;
2508    record.current_revision = Some(revision);
2509    let _ = record.transition(WorkflowStepState::Verified);
2510    let _ = record.transition(WorkflowStepState::OutputsExtracted);
2511    let _ = record.transition(WorkflowStepState::Committed);
2512}
2513
2514fn state_name(state: WorkflowStepState) -> &'static str {
2515    match state {
2516        WorkflowStepState::Pending => "pending",
2517        WorkflowStepState::Ready => "ready",
2518        WorkflowStepState::Preflight => "preflight",
2519        WorkflowStepState::Resolving => "resolving",
2520        WorkflowStepState::NotDispatched => "not_dispatched",
2521        WorkflowStepState::Dispatched => "dispatched",
2522        WorkflowStepState::EffectObserved => "effect_observed",
2523        WorkflowStepState::Verified => "verified",
2524        WorkflowStepState::OutputsExtracted => "outputs_extracted",
2525        WorkflowStepState::Committed => "committed",
2526        WorkflowStepState::FailedBeforeDispatch => "failed_before_dispatch",
2527        WorkflowStepState::FailedAfterDispatch => "failed_after_dispatch",
2528        WorkflowStepState::Indeterminate => "indeterminate",
2529        WorkflowStepState::Skipped => "skipped",
2530    }
2531}
2532
2533fn bound_workflow_text(value: &str, max_bytes: usize) -> String {
2534    if value.len() <= max_bytes {
2535        return value.to_string();
2536    }
2537    let mut end = max_bytes.saturating_sub(13);
2538    while end > 0 && !value.is_char_boundary(end) {
2539        end -= 1;
2540    }
2541    format!("{}\n[truncated]", &value[..end])
2542}
2543
2544/// A declared output captured after terminal verification.
2545#[derive(Debug, Clone, Serialize, Deserialize)]
2546#[serde(rename_all = "camelCase")]
2547pub struct WorkflowOutputDeclaration {
2548    #[serde(alias = "type")]
2549    pub value_type: WorkflowValueType,
2550    pub source: WorkflowOutputSource,
2551    #[serde(default)]
2552    pub required: bool,
2553    #[serde(default)]
2554    pub sensitive: bool,
2555}
2556
2557impl WorkflowOutputDeclaration {
2558    fn validate(&self, path: &str) -> Result<(), WorkflowValidationError> {
2559        let compatible = match self.source {
2560            WorkflowOutputSource::PageUrl => {
2561                matches!(
2562                    self.value_type,
2563                    WorkflowValueType::String | WorkflowValueType::Url
2564                )
2565            }
2566            WorkflowOutputSource::PageTitle | WorkflowOutputSource::VisibleText => true,
2567        };
2568        if !compatible {
2569            return Err(WorkflowValidationError::new(
2570                format!("{path}.valueType"),
2571                format!(
2572                    "{} output source requires a compatible value type",
2573                    self.source
2574                ),
2575            ));
2576        }
2577        Ok(())
2578    }
2579}
2580
2581/// Bounded, non-JavaScript sources for workflow outputs.
2582#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
2583#[serde(rename_all = "snake_case")]
2584pub enum WorkflowOutputSource {
2585    PageUrl,
2586    PageTitle,
2587    VisibleText,
2588}
2589
2590impl fmt::Display for WorkflowOutputSource {
2591    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
2592        formatter.write_str(match self {
2593            Self::PageUrl => "page_url",
2594            Self::PageTitle => "page_title",
2595            Self::VisibleText => "visible_text",
2596        })
2597    }
2598}
2599
2600/// A typed output value with its declared extraction source.
2601#[derive(Debug, Clone, Serialize, Deserialize)]
2602#[serde(rename_all = "camelCase")]
2603pub struct WorkflowOutput {
2604    pub value_type: WorkflowValueType,
2605    pub value: Value,
2606    #[serde(default, skip_serializing_if = "is_false")]
2607    pub redacted: bool,
2608    pub evidence: WorkflowOutputEvidence,
2609}
2610
2611fn is_false(value: &bool) -> bool {
2612    !*value
2613}
2614
2615/// Bounded provenance for a typed workflow output.
2616#[derive(Debug, Clone, Serialize, Deserialize)]
2617#[serde(rename_all = "camelCase")]
2618pub struct WorkflowOutputEvidence {
2619    pub source: WorkflowOutputSource,
2620    pub revision: u64,
2621}
2622
2623/// A path-aware validation failure.
2624#[derive(Debug, Clone, Serialize)]
2625pub struct WorkflowValidationError {
2626    pub path: String,
2627    pub reason: String,
2628}
2629
2630impl WorkflowValidationError {
2631    pub(crate) fn new(path: impl Into<String>, reason: impl Into<String>) -> Self {
2632        Self {
2633            path: path.into(),
2634            reason: reason.into(),
2635        }
2636    }
2637}
2638
2639impl fmt::Display for WorkflowValidationError {
2640    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
2641        write!(formatter, "{}: {}", self.path, self.reason)
2642    }
2643}
2644
2645impl std::error::Error for WorkflowValidationError {}
2646
2647fn require_object_fields(value: &Value, fields: &[&str]) -> Result<(), WorkflowValidationError> {
2648    let object = value.as_object().ok_or_else(|| {
2649        WorkflowValidationError::new("$", "workflow definition must be a JSON object")
2650    })?;
2651    for field in fields {
2652        if !object.contains_key(*field) {
2653            return Err(WorkflowValidationError::new(
2654                format!("$.{field}"),
2655                "required field is missing",
2656            ));
2657        }
2658    }
2659    Ok(())
2660}
2661
2662fn reject_unknown_fields(
2663    value: &Value,
2664    path: &str,
2665    allowed: &[&str],
2666) -> Result<(), WorkflowValidationError> {
2667    let object = value
2668        .as_object()
2669        .ok_or_else(|| WorkflowValidationError::new(path, "expected a JSON object"))?;
2670    if let Some(field) = object
2671        .keys()
2672        .find(|field| !allowed.contains(&field.as_str()))
2673    {
2674        return Err(WorkflowValidationError::new(
2675            format!("{path}.{field}"),
2676            "unknown workflow field",
2677        ));
2678    }
2679    Ok(())
2680}
2681
2682fn reject_predicate_fields(value: &Value, path: &str) -> Result<(), WorkflowValidationError> {
2683    let object = value
2684        .as_object()
2685        .ok_or_else(|| WorkflowValidationError::new(path, "expected a predicate object"))?;
2686    let allowed = [
2687        "urlEquals",
2688        "titleContains",
2689        "visible",
2690        "textContains",
2691        "popupOpened",
2692        "dialogOpen",
2693        "downloadStarted",
2694        "revisionEquals",
2695        "all",
2696        "any",
2697        "not",
2698    ];
2699    if object.len() != 1 {
2700        return Err(WorkflowValidationError::new(
2701            path,
2702            "predicate must contain exactly one recognized field",
2703        ));
2704    }
2705    let Some((field, nested)) = object.iter().next() else {
2706        return Err(WorkflowValidationError::new(
2707            path,
2708            "predicate must not be empty",
2709        ));
2710    };
2711    if !allowed.contains(&field.as_str()) {
2712        return Err(WorkflowValidationError::new(
2713            format!("{path}.{field}"),
2714            "unknown predicate field",
2715        ));
2716    }
2717    match field.as_str() {
2718        "all" | "any" => {
2719            let predicates = nested.as_array().ok_or_else(|| {
2720                WorkflowValidationError::new(format!("{path}.{field}"), "must be an array")
2721            })?;
2722            for (index, predicate) in predicates.iter().enumerate() {
2723                reject_predicate_fields(predicate, &format!("{path}.{field}[{index}]"))?;
2724            }
2725        }
2726        "not" => reject_predicate_fields(nested, &format!("{path}.not"))?,
2727        _ => {}
2728    }
2729    Ok(())
2730}
2731
2732fn validate_name(path: &str, value: &str) -> Result<(), WorkflowValidationError> {
2733    validate_bytes(path, value, 1, MAX_NAME_BYTES)?;
2734    if value.trim() != value {
2735        return Err(WorkflowValidationError::new(
2736            path,
2737            "must not have leading or trailing whitespace",
2738        ));
2739    }
2740    Ok(())
2741}
2742
2743fn validate_map_key(scope: &str, key: &str) -> Result<(), WorkflowValidationError> {
2744    validate_name(&format!("{scope}.{key}"), key)
2745}
2746
2747fn validate_bytes(
2748    path: &str,
2749    value: &str,
2750    minimum: usize,
2751    maximum: usize,
2752) -> Result<(), WorkflowValidationError> {
2753    if value.len() < minimum || value.len() > maximum {
2754        return Err(WorkflowValidationError::new(
2755            path,
2756            format!("must be {minimum}..={maximum} UTF-8 bytes"),
2757        ));
2758    }
2759    Ok(())
2760}
2761
2762fn validate_target(path: &str, target: &str) -> Result<(), WorkflowValidationError> {
2763    validate_bytes(path, target, 1, MAX_TARGET_BYTES)
2764}
2765
2766fn validate_predicate(
2767    predicate: &VerificationPredicate,
2768    path: &str,
2769) -> Result<(), WorkflowValidationError> {
2770    predicate
2771        .validate(0)
2772        .map_err(|error| WorkflowValidationError::new(path, error.to_string()))
2773}
2774
2775fn validate_batch_step(action: &BatchStep, path: &str) -> Result<(), WorkflowValidationError> {
2776    match action {
2777        BatchStep::Navigate { url, timeout_ms } => {
2778            if Url::parse(url).is_err() {
2779                return Err(WorkflowValidationError::new(
2780                    format!("{path}.url"),
2781                    "must be an absolute URL",
2782                ));
2783            }
2784            if *timeout_ms == 0 || *timeout_ms > MAX_DURATION_MS {
2785                return Err(WorkflowValidationError::new(
2786                    format!("{path}.timeoutMs"),
2787                    format!("must be 1..={MAX_DURATION_MS}"),
2788                ));
2789            }
2790        }
2791        BatchStep::Click { target }
2792        | BatchStep::Check { target }
2793        | BatchStep::Uncheck { target }
2794        | BatchStep::Clear { target } => validate_target(&format!("{path}.target"), target)?,
2795        BatchStep::Type { text, target } => {
2796            validate_bytes(&format!("{path}.text"), text, 0, MAX_TEXT_BYTES)?;
2797            if let Some(target) = target {
2798                validate_target(&format!("{path}.target"), target)?;
2799            }
2800        }
2801        BatchStep::Select { target, value } => {
2802            validate_target(&format!("{path}.target"), target)?;
2803            validate_bytes(&format!("{path}.value"), value, 1, MAX_TEXT_BYTES)?;
2804        }
2805        BatchStep::Scroll { dx, dy } => {
2806            if !dx.is_finite()
2807                || !dy.is_finite()
2808                || dx.abs() > 1_000_000.0
2809                || dy.abs() > 1_000_000.0
2810            {
2811                return Err(WorkflowValidationError::new(
2812                    path,
2813                    "scroll deltas must be finite and bounded",
2814                ));
2815            }
2816        }
2817        BatchStep::Wait {
2818            condition,
2819            timeout_ms,
2820        } => {
2821            validate_bytes(
2822                &format!("{path}.condition"),
2823                condition,
2824                1,
2825                MAX_WAIT_CONDITION_BYTES,
2826            )?;
2827            if *timeout_ms == 0 || *timeout_ms > MAX_DURATION_MS {
2828                return Err(WorkflowValidationError::new(
2829                    format!("{path}.timeoutMs"),
2830                    format!("must be 1..={MAX_DURATION_MS}"),
2831                ));
2832            }
2833        }
2834        BatchStep::Observe { .. }
2835        | BatchStep::Screenshot
2836        | BatchStep::AcceptDialog
2837        | BatchStep::DismissDialog => {}
2838        BatchStep::Evaluate { .. } => {
2839            return Err(WorkflowValidationError::new(
2840                path,
2841                "evaluate is not permitted in a declarative workflow",
2842            ));
2843        }
2844    }
2845    Ok(())
2846}
2847
2848#[cfg(test)]
2849mod tests {
2850    use super::*;
2851    use crate::browser::session::{
2852        FingerprintInvalidation, SemanticIntentCandidate, SemanticIntentPurpose,
2853        SemanticRegionKind, SemanticTargetFingerprint,
2854    };
2855    use serde_json::json;
2856
2857    fn definition() -> WorkflowDefinition {
2858        WorkflowDefinition {
2859            schema_version: WORKFLOW_SCHEMA_VERSION,
2860            name: "example".into(),
2861            workflow_version: "1.0.0".into(),
2862            description: None,
2863            inputs: BTreeMap::from([(
2864                "url".into(),
2865                WorkflowInput {
2866                    value_type: WorkflowValueType::Url,
2867                    required: true,
2868                    max_length: Some(2_048),
2869                    sensitive: None,
2870                },
2871            )]),
2872            budgets: WorkflowBudgets {
2873                max_steps: 2,
2874                max_duration_ms: 30_000,
2875                max_retries: 1,
2876                max_extracted_bytes: 4_096,
2877            },
2878            preconditions: vec![],
2879            steps: vec![WorkflowStep {
2880                id: "open".into(),
2881                action: BatchStep::Navigate {
2882                    url: "https://example.com".into(),
2883                    timeout_ms: 20_000,
2884                },
2885                intent: None,
2886                when: None,
2887                expect: Some(VerificationPredicate::TitleContains {
2888                    value: "Example".into(),
2889                }),
2890                before_retry: None,
2891                transaction: WorkflowTransactionClass::ReadOnly,
2892                idempotency_key: None,
2893                max_retries: 0,
2894                repeat: 1,
2895            }],
2896            terminal_condition: VerificationPredicate::UrlEquals {
2897                value: "https://example.com/".into(),
2898            },
2899            outputs: BTreeMap::new(),
2900        }
2901    }
2902
2903    #[test]
2904    fn canonical_json_is_stable_and_uses_camel_case() {
2905        let workflow = definition();
2906        let first = workflow.to_canonical_json().unwrap();
2907        let second = workflow.to_canonical_json().unwrap();
2908        assert_eq!(first, second);
2909        assert!(first.contains("\"schemaVersion\":1"));
2910        assert!(first.contains("\"timeoutMs\":20000"));
2911        assert!(first.contains("\"workflowVersion\":\"1.0.0\""));
2912    }
2913
2914    #[test]
2915    fn before_retry_marker_is_canonical_and_validated() {
2916        let mut workflow = definition();
2917        workflow.steps[0].before_retry = Some(VerificationPredicate::TitleContains {
2918            value: "Already saved".into(),
2919        });
2920        let json = workflow.to_canonical_json().unwrap();
2921        assert!(json.contains("\"beforeRetry\":{"));
2922        let parsed = WorkflowDefinition::from_json(&json).unwrap();
2923        assert!(parsed.steps[0].before_retry.is_some());
2924    }
2925
2926    #[test]
2927    fn type_alias_is_accepted_but_canonical_json_uses_value_type() {
2928        let mut value = serde_json::to_value(definition()).unwrap();
2929        let input = value["inputs"]["url"].as_object_mut().unwrap();
2930        let value_type = input.remove("valueType").unwrap();
2931        input.insert("type".into(), value_type);
2932
2933        let parsed = WorkflowDefinition::from_value(value).unwrap();
2934        let canonical = parsed.to_canonical_json().unwrap();
2935        assert!(canonical.contains("\"valueType\":\"url\""));
2936        assert!(!canonical.contains("\"type\":\"url\""));
2937    }
2938
2939    #[test]
2940    fn effect_marker_commit_follows_evidence_states_without_dispatch() {
2941        let mut record = WorkflowStepRecord::new("save");
2942        record.transition(WorkflowStepState::Ready).unwrap();
2943        commit_workflow_effect_marker(&mut record, 9);
2944        assert_eq!(record.state, WorkflowStepState::Committed);
2945        assert!(!record.dispatch_acknowledged);
2946        assert!(record.effect_observed);
2947        assert!(record.postcondition_verified);
2948        assert_eq!(record.current_revision, Some(9));
2949    }
2950
2951    #[test]
2952    fn from_json_reports_missing_top_level_path() {
2953        let mut value = serde_json::to_value(definition()).unwrap();
2954        value.as_object_mut().unwrap().remove("steps");
2955        let error = WorkflowDefinition::from_value(value).unwrap_err();
2956        assert_eq!(error.path, "$.steps");
2957    }
2958
2959    #[test]
2960    fn unknown_definition_fields_fail_before_deserialization() {
2961        let mut value = serde_json::to_value(definition()).unwrap();
2962        value
2963            .as_object_mut()
2964            .unwrap()
2965            .insert("futureField".into(), json!(true));
2966        let error = WorkflowDefinition::from_value(value).unwrap_err();
2967        assert_eq!(error.path, "$.futureField");
2968    }
2969
2970    #[test]
2971    fn semantic_intent_steps_round_trip_with_bounded_defaults() {
2972        let mut value = serde_json::to_value(definition()).unwrap();
2973        value["steps"][0] = json!({
2974            "id": "continue",
2975            "intent": {
2976                "action": "click",
2977                "purpose": "continueCheckout",
2978                "scope": {"regionKind": "checkoutSummary"},
2979                "resolutionPolicy": "requireUniqueHighConfidence"
2980            },
2981            "transaction": "idempotent"
2982        });
2983        let workflow = WorkflowDefinition::from_value(value).unwrap();
2984        let intent = workflow.steps[0].intent.as_ref().unwrap();
2985        assert_eq!(intent.action, SemanticIntentAction::Click);
2986        assert_eq!(intent.purpose.as_deref(), Some("continueCheckout"));
2987        assert_eq!(
2988            intent
2989                .execution_request("steps[0].intent")
2990                .unwrap()
2991                .request
2992                .intent,
2993            "continue checkout"
2994        );
2995        let canonical = workflow.to_canonical_json().unwrap();
2996        assert!(canonical.contains("\"resolutionPolicy\":\"requireUniqueHighConfidence\""));
2997        assert!(!canonical.contains("\"action\":\"navigate\""));
2998    }
2999
3000    #[test]
3001    fn semantic_intent_steps_reject_ambiguous_shape_and_missing_values() {
3002        let mut value = serde_json::to_value(definition()).unwrap();
3003        value["steps"][0] = json!({
3004            "id": "bad",
3005            "intent": {
3006                "action": "type",
3007                "purpose": "enterSearch",
3008                "intent": "enter search",
3009                "resolutionPolicy": "requireUniqueHighConfidence"
3010            },
3011            "transaction": "idempotent"
3012        });
3013        let error = WorkflowDefinition::from_value(value).unwrap_err();
3014        assert_eq!(error.path, "steps[0].intent.purpose");
3015
3016        let mut value = serde_json::to_value(definition()).unwrap();
3017        value["steps"][0] = json!({
3018            "id": "bad",
3019            "intent": {
3020                "action": "type",
3021                "purpose": "enterSearch",
3022                "resolutionPolicy": "requireUniqueHighConfidence"
3023            },
3024            "transaction": "idempotent"
3025        });
3026        let error = WorkflowDefinition::from_value(value).unwrap_err();
3027        assert_eq!(error.path, "steps[0].intent.value");
3028    }
3029
3030    #[test]
3031    fn unknown_predicate_fields_fail_with_their_json_path() {
3032        let mut value = serde_json::to_value(definition()).unwrap();
3033        value["terminalCondition"] = json!({"titleContains": "Example", "future": true});
3034        let error = WorkflowDefinition::from_value(value).unwrap_err();
3035        assert_eq!(error.path, "terminalCondition");
3036    }
3037
3038    #[test]
3039    fn duplicate_step_ids_are_rejected() {
3040        let mut workflow = definition();
3041        workflow.steps.push(WorkflowStep {
3042            id: "open".into(),
3043            action: BatchStep::Screenshot,
3044            intent: None,
3045            when: None,
3046            expect: None,
3047            before_retry: None,
3048            transaction: WorkflowTransactionClass::ReadOnly,
3049            idempotency_key: None,
3050            max_retries: 0,
3051            repeat: 1,
3052        });
3053        let error = workflow.validate().unwrap_err();
3054        assert_eq!(error.path, "steps[1].id");
3055    }
3056
3057    #[test]
3058    fn invalid_budget_reports_exact_path() {
3059        let mut workflow = definition();
3060        workflow.budgets.max_steps = 0;
3061        let error = workflow.validate().unwrap_err();
3062        assert_eq!(error.path, "budgets.maxSteps");
3063    }
3064
3065    #[test]
3066    fn conditional_idempotency_requires_a_key() {
3067        let mut workflow = definition();
3068        workflow.steps[0].transaction = WorkflowTransactionClass::ConditionallyIdempotent;
3069        let error = workflow.validate().unwrap_err();
3070        assert_eq!(error.path, "steps[0].idempotencyKey");
3071    }
3072
3073    #[test]
3074    fn duplicate_idempotency_keys_are_rejected() {
3075        let mut workflow = definition();
3076        workflow.steps[0].transaction = WorkflowTransactionClass::ConditionallyIdempotent;
3077        workflow.steps[0].idempotency_key = Some("save-once".into());
3078        workflow.steps.push(WorkflowStep {
3079            id: "second".into(),
3080            action: BatchStep::Screenshot,
3081            intent: None,
3082            when: None,
3083            expect: None,
3084            before_retry: None,
3085            transaction: WorkflowTransactionClass::ConditionallyIdempotent,
3086            idempotency_key: Some("save-once".into()),
3087            max_retries: 0,
3088            repeat: 1,
3089        });
3090        workflow.budgets.max_steps = 2;
3091        let error = workflow.validate().unwrap_err();
3092        assert_eq!(error.path, "steps[1].idempotencyKey");
3093    }
3094
3095    #[test]
3096    fn unknown_steps_cannot_request_automatic_retries() {
3097        let mut workflow = definition();
3098        workflow.steps[0].transaction = WorkflowTransactionClass::Unknown;
3099        workflow.budgets.max_retries = 1;
3100        workflow.steps[0].max_retries = 1;
3101        let error = workflow.validate().unwrap_err();
3102        assert_eq!(error.path, "steps[0].maxRetries");
3103    }
3104
3105    #[test]
3106    fn bounded_repetition_requires_retry_safe_class() {
3107        let mut workflow = definition();
3108        workflow.budgets.max_steps = 2;
3109        workflow.steps[0].repeat = 2;
3110        workflow.steps[0].transaction = WorkflowTransactionClass::Unknown;
3111        let error = workflow.validate().unwrap_err();
3112        assert_eq!(error.path, "steps[0].repeat");
3113    }
3114
3115    #[test]
3116    fn retry_policy_never_replays_after_dispatch() {
3117        assert!(can_retry_before_dispatch(
3118            WorkflowTransactionClass::Idempotent,
3119            false,
3120            1,
3121            1
3122        ));
3123        assert!(!can_retry_before_dispatch(
3124            WorkflowTransactionClass::NonIdempotent,
3125            false,
3126            1,
3127            1
3128        ));
3129        assert!(!can_retry_before_dispatch(
3130            WorkflowTransactionClass::Idempotent,
3131            true,
3132            1,
3133            1
3134        ));
3135    }
3136
3137    #[test]
3138    fn workflow_checkpoint_is_deterministic_and_redacted() {
3139        let checkpoint = WorkflowCheckpoint {
3140            schema_version: WORKFLOW_CHECKPOINT_SCHEMA_VERSION,
3141            run_id: "run_test".into(),
3142            workflow_name: "example".into(),
3143            workflow_version: "1.0.0".into(),
3144            definition_hash: "a".repeat(64),
3145            status: WorkflowRunStatus::Failed,
3146            next_step_index: 1,
3147            steps: vec![
3148                WorkflowCheckpointStep {
3149                    id: "open".into(),
3150                    state: WorkflowStepState::Committed,
3151                    attempts: 1,
3152                    history: Vec::new(),
3153                    execution_ids: Vec::new(),
3154                    dispatch_acknowledged: false,
3155                    effect_observed: false,
3156                    postcondition_verified: false,
3157                    retry_safe: false,
3158                    previous_revision: None,
3159                    current_revision: None,
3160                    branch_decision: None,
3161                    intent_evidence: None,
3162                },
3163                WorkflowCheckpointStep {
3164                    id: "save".into(),
3165                    state: WorkflowStepState::FailedBeforeDispatch,
3166                    attempts: 1,
3167                    history: Vec::new(),
3168                    execution_ids: Vec::new(),
3169                    dispatch_acknowledged: false,
3170                    effect_observed: false,
3171                    postcondition_verified: false,
3172                    retry_safe: false,
3173                    previous_revision: None,
3174                    current_revision: None,
3175                    branch_decision: None,
3176                    intent_evidence: None,
3177                },
3178            ],
3179            page: WorkflowCheckpointPage {
3180                target_id: "target".into(),
3181                frame_id: "frame".into(),
3182                url: "https://example.com".into(),
3183                title: "Example".into(),
3184                revision: 3,
3185            },
3186        };
3187        let first = checkpoint.to_canonical_json().unwrap();
3188        let second = checkpoint.to_canonical_json().unwrap();
3189        assert_eq!(first, second);
3190        assert!(!first.contains("password"));
3191        assert_eq!(
3192            crate::BrowserSession::parse_workflow_checkpoint(&first)
3193                .unwrap()
3194                .next_step_index,
3195            1
3196        );
3197    }
3198
3199    #[test]
3200    fn minimal_workflow_fixture_round_trips() {
3201        let workflow = WorkflowDefinition::from_json(include_str!(
3202            "../../../tests/fixtures/workflow-minimal.json"
3203        ))
3204        .unwrap();
3205        assert_eq!(workflow.name, "open-example");
3206        assert!(workflow.preconditions.is_empty());
3207        assert!(workflow.to_canonical_json().is_ok());
3208    }
3209
3210    #[test]
3211    fn evaluate_is_rejected_before_execution() {
3212        let mut workflow = definition();
3213        workflow.steps[0].action = BatchStep::Evaluate {
3214            expression: "document.title".into(),
3215        };
3216        let error = workflow.validate().unwrap_err();
3217        assert!(error.reason.contains("not permitted"));
3218    }
3219
3220    #[test]
3221    fn inputs_are_type_checked_and_bounded() {
3222        let workflow = definition();
3223        let values = BTreeMap::from([("url".into(), json!("https://example.com"))]);
3224        workflow.validate_inputs(&values).unwrap();
3225
3226        let bad_values = BTreeMap::from([("url".into(), json!("not a url"))]);
3227        let error = workflow.validate_inputs(&bad_values).unwrap_err();
3228        assert_eq!(error.path, "inputs.url");
3229    }
3230
3231    #[test]
3232    fn resolve_actions_substitutes_bounded_inputs() {
3233        let mut workflow = definition();
3234        workflow.steps[0].action = BatchStep::Navigate {
3235            url: "${inputs.url}".into(),
3236            timeout_ms: 20_000,
3237        };
3238        let values = BTreeMap::from([("url".into(), json!("https://docs.example.com"))]);
3239        let steps = workflow.resolve_actions(&values).unwrap();
3240        let BatchStep::Navigate { url, .. } = &steps[0].action else {
3241            panic!("expected navigate action");
3242        };
3243        assert_eq!(url, "https://docs.example.com");
3244    }
3245
3246    #[test]
3247    fn resolve_actions_rejects_unknown_placeholders_before_dispatch() {
3248        let mut workflow = definition();
3249        workflow.steps[0].action = BatchStep::Click {
3250            target: "name=${inputs.missing}".into(),
3251        };
3252        let values = BTreeMap::from([("url".into(), json!("https://example.com"))]);
3253        let error = workflow.resolve_actions(&values).unwrap_err();
3254        assert_eq!(error.path, "steps[0].action.target");
3255    }
3256
3257    #[test]
3258    fn typed_output_values_require_strict_scalar_conversions() {
3259        assert_eq!(
3260            typed_output_value("count", WorkflowValueType::Integer, " 42 ").unwrap(),
3261            json!(42)
3262        );
3263        assert_eq!(
3264            typed_output_value("ready", WorkflowValueType::Boolean, "false").unwrap(),
3265            json!(false)
3266        );
3267        assert!(typed_output_value("count", WorkflowValueType::Integer, "4.2").is_err());
3268        assert!(typed_output_value("ready", WorkflowValueType::Boolean, "yes").is_err());
3269    }
3270
3271    #[test]
3272    fn sensitive_output_serialization_contains_no_literal_value() {
3273        let output = WorkflowOutput {
3274            value_type: WorkflowValueType::String,
3275            value: Value::Null,
3276            redacted: true,
3277            evidence: WorkflowOutputEvidence {
3278                source: WorkflowOutputSource::VisibleText,
3279                revision: 4,
3280            },
3281        };
3282        let serialized = serde_json::to_string(&output).unwrap();
3283        assert!(serialized.contains("\"redacted\":true"));
3284        assert!(!serialized.contains("secret"));
3285    }
3286
3287    #[test]
3288    fn recorder_keeps_semantic_targets_and_redacts_typed_values() {
3289        let mut recorder = WorkflowRecorder::new("checkout", "1.0.0");
3290        recorder
3291            .record_click("continue", "button", "Continue", None)
3292            .unwrap();
3293        recorder
3294            .record_type_input("email", "textbox", "Email", "email")
3295            .unwrap();
3296        let draft = recorder.draft();
3297        let BatchStep::Click { target } = &draft.steps[0].action else {
3298            panic!("expected semantic click draft");
3299        };
3300        assert_eq!(target, "role=button;name=Continue");
3301        let serialized = serde_json::to_string(draft).unwrap();
3302        assert!(!serialized.contains("password-value"));
3303        assert!(serialized.contains("${inputs.email}"));
3304        assert!(draft.steps[1].review_required);
3305        let inferred = recorder.inferred_inputs();
3306        assert_eq!(inferred["email"].value_type, WorkflowValueType::String);
3307        assert_eq!(inferred["email"].sensitive, None);
3308        recorder
3309            .attach_expect_to_last(VerificationPredicate::TextContains {
3310                value: "Checkout complete".into(),
3311            })
3312            .unwrap();
3313        assert!(matches!(
3314            recorder.draft().steps[1].expect,
3315            Some(VerificationPredicate::TextContains { .. })
3316        ));
3317    }
3318
3319    #[test]
3320    fn recorder_captures_semantic_evidence_without_replay_handles_or_query_values() {
3321        let request = SemanticIntentRequest {
3322            schema_version: INTENT_RESOLUTION_SCHEMA_VERSION,
3323            intent: "submit order".into(),
3324            action: SemanticIntentAction::Click,
3325            scope: IntentScope::default(),
3326            constraints: IntentConstraints::default(),
3327            resolution_policy: SemanticResolutionPolicy::RequireUniqueHighConfidence,
3328            expected_revision: None,
3329        };
3330        let route = SemanticRouteIdentity {
3331            target_id: "target-7".into(),
3332            frame_id: "frame-2".into(),
3333            url: "https://shop.example/orders?token=secret#confirmation".into(),
3334        };
3335        let result = SemanticIntentResult {
3336            schema_version: INTENT_RESOLUTION_SCHEMA_VERSION,
3337            intent: request.intent.clone(),
3338            action: request.action,
3339            normalized_intent: "submit order".into(),
3340            resolution: SemanticResolution::UniqueHighConfidence,
3341            policy_decision: IntentPolicyDecision::Allowed,
3342            route: Some(route.clone()),
3343            revision: Some(7),
3344            candidates: vec![SemanticIntentCandidate {
3345                id: "candidate-1".into(),
3346                reference: "r7:backend-secret".into(),
3347                role: "button".into(),
3348                name: "Submit order".into(),
3349                input_type: None,
3350                region_id: Some("checkout-region".into()),
3351                region_kind: Some(SemanticRegionKind::CheckoutSummary),
3352                confidence: IntentConfidence::High,
3353                evidence: Vec::new(),
3354                fingerprint: Some(SemanticTargetFingerprint {
3355                    revision: 7,
3356                    route: route.clone(),
3357                    role: "button".into(),
3358                    name: "Submit order".into(),
3359                    input_type: None,
3360                    region_id: Some("checkout-region".into()),
3361                    region_kind: Some(SemanticRegionKind::CheckoutSummary),
3362                    purpose: SemanticIntentPurpose::Submit,
3363                    invalidated_by: vec![FingerprintInvalidation::Revision],
3364                }),
3365            }],
3366            excluded_candidates: Vec::new(),
3367            excluded_count: 0,
3368            selected_candidate: Some("candidate-1".into()),
3369            suggested_constraints: Vec::new(),
3370            reason: None,
3371        };
3372        let mut recorder = WorkflowRecorder::new("checkout", "1.0.0");
3373        recorder
3374            .record_semantic_intent(
3375                "submit",
3376                &request,
3377                &result,
3378                None::<String>,
3379                WorkflowTransactionClass::NonIdempotent,
3380                Some(VerificationPredicate::TextContains {
3381                    value: "Order submitted".into(),
3382                }),
3383            )
3384            .unwrap();
3385
3386        let draft = recorder.draft();
3387        let step = &draft.steps[0];
3388        assert_eq!(
3389            step.target.as_ref().unwrap().region_kind,
3390            Some(SemanticRegionKind::CheckoutSummary)
3391        );
3392        assert_eq!(step.semantic.as_ref().unwrap().revision, Some(7));
3393        assert!(step.semantic.as_ref().unwrap().target_fingerprint.is_some());
3394        let serialized = serde_json::to_string(draft).unwrap();
3395        assert!(!serialized.contains("backend-secret"));
3396        assert!(!serialized.contains("token=secret"));
3397        assert!(!serialized.contains("target-7"));
3398        assert!(!serialized.contains("frame-2"));
3399
3400        let definition = recorder
3401            .into_definition(
3402                BTreeMap::new(),
3403                WorkflowBudgets {
3404                    max_steps: 1,
3405                    max_duration_ms: 30_000,
3406                    max_retries: 0,
3407                    max_extracted_bytes: 4_096,
3408                },
3409                VerificationPredicate::TextContains {
3410                    value: "Order submitted".into(),
3411                },
3412                BTreeMap::new(),
3413            )
3414            .unwrap();
3415        assert!(definition.steps[0].intent.is_some());
3416        assert!(definition.steps[0].expect.is_some());
3417    }
3418
3419    #[test]
3420    fn recorder_keeps_ambiguous_semantic_results_unselected() {
3421        let request = SemanticIntentRequest {
3422            schema_version: INTENT_RESOLUTION_SCHEMA_VERSION,
3423            intent: "open settings".into(),
3424            action: SemanticIntentAction::Click,
3425            scope: IntentScope::default(),
3426            constraints: IntentConstraints::default(),
3427            resolution_policy: SemanticResolutionPolicy::RequireUniqueHighConfidence,
3428            expected_revision: None,
3429        };
3430        let candidate = |id: &str| SemanticIntentCandidate {
3431            id: id.into(),
3432            reference: format!("{id}:ref"),
3433            role: "button".into(),
3434            name: "Settings".into(),
3435            input_type: None,
3436            region_id: None,
3437            region_kind: None,
3438            confidence: IntentConfidence::High,
3439            evidence: Vec::new(),
3440            fingerprint: None,
3441        };
3442        let result = SemanticIntentResult {
3443            schema_version: INTENT_RESOLUTION_SCHEMA_VERSION,
3444            intent: request.intent.clone(),
3445            action: request.action,
3446            normalized_intent: request.intent.clone(),
3447            resolution: SemanticResolution::Ambiguous,
3448            policy_decision: IntentPolicyDecision::Rejected,
3449            route: None,
3450            revision: Some(3),
3451            candidates: vec![candidate("one"), candidate("two")],
3452            excluded_candidates: Vec::new(),
3453            excluded_count: 0,
3454            selected_candidate: None,
3455            suggested_constraints: Vec::new(),
3456            reason: Some("two candidates remain".into()),
3457        };
3458        let mut recorder = WorkflowRecorder::new("settings", "1.0.0");
3459        recorder
3460            .record_semantic_intent(
3461                "open-settings",
3462                &request,
3463                &result,
3464                None::<String>,
3465                WorkflowTransactionClass::Unknown,
3466                None,
3467            )
3468            .unwrap();
3469        let step = &recorder.draft().steps[0];
3470        assert!(step.target.is_none());
3471        assert_eq!(step.confidence, WorkflowRecordingConfidence::Low);
3472        assert!(step.semantic.as_ref().unwrap().ambiguous);
3473        assert!(step.review_required);
3474    }
3475
3476    #[test]
3477    fn workflow_step_flattens_batch_action() {
3478        let value = serde_json::to_value(&definition().steps[0]).unwrap();
3479        assert_eq!(value["id"], "open");
3480        assert_eq!(value["action"], "navigate");
3481        assert_eq!(value["timeoutMs"], 20_000);
3482    }
3483
3484    #[test]
3485    fn state_machine_accepts_linear_commit_and_rejects_invalid_jump() {
3486        assert!(WorkflowStepState::Pending.can_transition_to(WorkflowStepState::Ready));
3487        assert!(WorkflowStepState::Resolving.can_transition_to(WorkflowStepState::Dispatched));
3488        assert!(!WorkflowStepState::Pending.can_transition_to(WorkflowStepState::Committed));
3489
3490        let mut record = WorkflowStepRecord::new("open");
3491        for state in [
3492            WorkflowStepState::Ready,
3493            WorkflowStepState::Preflight,
3494            WorkflowStepState::Resolving,
3495            WorkflowStepState::Dispatched,
3496            WorkflowStepState::EffectObserved,
3497            WorkflowStepState::Verified,
3498            WorkflowStepState::OutputsExtracted,
3499            WorkflowStepState::Committed,
3500        ] {
3501            record.transition(state).unwrap();
3502        }
3503        assert_eq!(record.state, WorkflowStepState::Committed);
3504        assert_eq!(record.history.len(), 9);
3505        assert!(record.transition(WorkflowStepState::Preflight).is_err());
3506        let trace = WorkflowTrace::from_steps(&[record]);
3507        trace.validate().unwrap();
3508        assert_eq!(trace.events[0].sequence, 0);
3509        assert_eq!(
3510            trace.events.last().unwrap().state,
3511            WorkflowStepState::Committed
3512        );
3513    }
3514
3515    #[test]
3516    fn step_record_serializes_bounded_execution_evidence() {
3517        let mut record = WorkflowStepRecord::new("open");
3518        record.execution_ids = vec!["act_7".into(), "act_8".into()];
3519        record.dispatch_acknowledged = true;
3520        record.effect_observed = true;
3521        record.postcondition_verified = true;
3522        record.retry_safe = false;
3523        record.previous_revision = Some(7);
3524        record.current_revision = Some(8);
3525        record.intent_evidence = Some(WorkflowIntentEvidence {
3526            resolution_id: "res_1".into(),
3527            candidate_id: "candidate_1".into(),
3528            revision: 8,
3529            resolution: crate::browser::session::SemanticResolution::Exact,
3530            policy_decision: crate::browser::session::IntentPolicyDecision::Allowed,
3531            confidence: crate::browser::session::IntentConfidence::Exact,
3532            fingerprint: None,
3533        });
3534
3535        let trace = WorkflowTrace::from_steps(std::slice::from_ref(&record));
3536        assert_eq!(trace.intent_resolutions.len(), 1);
3537        let value = serde_json::to_value(record).unwrap();
3538        assert_eq!(value["executionIds"], serde_json::json!(["act_7", "act_8"]));
3539        assert_eq!(value["dispatchAcknowledged"], true);
3540        assert_eq!(value["effectObserved"], true);
3541        assert_eq!(value["postconditionVerified"], true);
3542        assert_eq!(value["retrySafe"], false);
3543        assert_eq!(value["previousRevision"], 7);
3544        assert_eq!(value["currentRevision"], 8);
3545        assert_eq!(value["intentEvidence"]["candidateId"], "candidate_1");
3546    }
3547
3548    #[test]
3549    fn budget_exhaustion_is_a_typed_run_status() {
3550        let result = WorkflowRunResult::budget_exhausted(
3551            &definition(),
3552            "run_test".into(),
3553            vec![WorkflowStepRecord::new("open")],
3554            Some("open".into()),
3555            "maxSteps exhausted",
3556            3,
3557            3,
3558        );
3559        assert_eq!(result.status, WorkflowRunStatus::BudgetExhausted);
3560        assert_eq!(result.trace.run_id.as_deref(), Some("run_test"));
3561        let value = serde_json::to_value(result).unwrap();
3562        assert_eq!(value["status"], "budget_exhausted");
3563    }
3564
3565    #[test]
3566    fn trace_schema_version_is_independent_and_validated() {
3567        let trace = WorkflowTrace::from_steps(&[]);
3568        assert_eq!(trace.schema_version, WORKFLOW_TRACE_SCHEMA_VERSION);
3569        trace.validate().unwrap();
3570
3571        let mut unsupported = trace;
3572        unsupported.schema_version = WORKFLOW_TRACE_SCHEMA_VERSION + 1;
3573        let error = unsupported.validate().unwrap_err();
3574        assert_eq!(error.path, "trace.schemaVersion");
3575    }
3576
3577    #[test]
3578    fn post_dispatch_failures_require_resume_reconciliation() {
3579        let result = WorkflowRunResult::resume_required(
3580            &definition(),
3581            "run_test".into(),
3582            vec![WorkflowStepRecord::new("open")],
3583            Some("open".into()),
3584            "postcondition was not proven",
3585            3,
3586            4,
3587        );
3588        assert_eq!(result.status, WorkflowRunStatus::ResumeRequired);
3589        assert_eq!(
3590            serde_json::to_value(result).unwrap()["status"],
3591            "resume_required"
3592        );
3593    }
3594
3595    #[test]
3596    fn trace_replay_preserves_attempt_boundaries() {
3597        let mut record = WorkflowStepRecord::new("open");
3598        record.transition(WorkflowStepState::Ready).unwrap();
3599        record.transition(WorkflowStepState::Preflight).unwrap();
3600        record.attempts = 1;
3601        record.transition(WorkflowStepState::Resolving).unwrap();
3602        record.transition(WorkflowStepState::NotDispatched).unwrap();
3603        record.fail(WorkflowStepState::FailedBeforeDispatch, "before dispatch");
3604        record.transition(WorkflowStepState::Ready).unwrap();
3605        record.transition(WorkflowStepState::Preflight).unwrap();
3606        record.attempts = 2;
3607        record.transition(WorkflowStepState::Resolving).unwrap();
3608        record.transition(WorkflowStepState::Dispatched).unwrap();
3609        record
3610            .transition(WorkflowStepState::EffectObserved)
3611            .unwrap();
3612        record.transition(WorkflowStepState::Verified).unwrap();
3613        record
3614            .transition(WorkflowStepState::OutputsExtracted)
3615            .unwrap();
3616        record.transition(WorkflowStepState::Committed).unwrap();
3617
3618        let workflow = definition();
3619        let trace = WorkflowTrace::from_steps(&[record]);
3620        let replayed = trace.replay(&workflow).unwrap();
3621        assert_eq!(trace.events[2].attempt, 1);
3622        assert_eq!(trace.events[7].attempt, 2);
3623        assert_eq!(replayed[0].state, WorkflowStepState::Committed);
3624        assert_eq!(replayed[0].attempts, 2);
3625    }
3626
3627    #[test]
3628    fn trace_replay_rejects_a_prefix_that_skips_the_first_step() {
3629        let mut workflow = definition();
3630        workflow.steps.push(WorkflowStep {
3631            id: "save".into(),
3632            action: BatchStep::Screenshot,
3633            intent: None,
3634            when: None,
3635            expect: None,
3636            before_retry: None,
3637            transaction: WorkflowTransactionClass::ReadOnly,
3638            idempotency_key: None,
3639            max_retries: 0,
3640            repeat: 1,
3641        });
3642        let trace = WorkflowTrace::from_steps(&[WorkflowStepRecord::new("save")]);
3643        let error = trace.replay(&workflow).unwrap_err();
3644        assert_eq!(error.path, "trace.events[0].stepId");
3645    }
3646
3647    #[test]
3648    fn conditional_steps_record_and_replay_branch_decisions() {
3649        let mut workflow = definition();
3650        let predicate = VerificationPredicate::TitleContains {
3651            value: "Example".into(),
3652        };
3653        workflow.steps[0].when = Some(predicate.clone());
3654        let mut record = WorkflowStepRecord::new("open");
3655        record.transition(WorkflowStepState::Ready).unwrap();
3656        record.branch_decision = Some(WorkflowBranchDecision {
3657            step_id: "open".into(),
3658            predicate: predicate.clone(),
3659            matched: false,
3660        });
3661        record.transition(WorkflowStepState::Skipped).unwrap();
3662        let trace = WorkflowTrace::from_steps(&[record]);
3663        assert!(!trace.branch_decisions[0].matched);
3664        let replayed = trace.replay(&workflow).unwrap();
3665        assert_eq!(replayed[0].state, WorkflowStepState::Skipped);
3666        assert_eq!(
3667            replayed[0].branch_decision.as_ref().unwrap().predicate,
3668            predicate
3669        );
3670    }
3671}