1use 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
27pub 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#[derive(Debug, Clone, Serialize, Deserialize)]
50#[serde(rename_all = "camelCase")]
51pub struct WorkflowDefinition {
52 pub schema_version: u32,
54 pub name: String,
56 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 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 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 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 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 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 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#[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#[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#[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#[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#[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#[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 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#[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 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#[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#[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#[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 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#[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#[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#[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#[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#[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 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 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 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 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 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 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 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 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 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#[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#[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#[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#[derive(Debug, Clone, Serialize, Deserialize)]
2617#[serde(rename_all = "camelCase")]
2618pub struct WorkflowOutputEvidence {
2619 pub source: WorkflowOutputSource,
2620 pub revision: u64,
2621}
2622
2623#[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}