feat(docs): update examples in observers, recovery, and saga sections to use async main function

Author: nassor

docs/content/observers/_index.md

@@ -77,15 +77,19 @@ impl WorkflowObserver for TaskCounter {
     }
 }
 
-let counter = Arc::new(TaskCounter::default());
-
-let workflow = Workflow::bare()
-    .register(Step::Start, DoWork)
-    .add_exit_state(Step::Done)
-    .with_observer(counter.clone());
-
-workflow.orchestrate(Step::Start).await?;
-assert_eq!(counter.0.load(Ordering::Relaxed), 1);
+#[tokio::main]
+async fn main() -> Result<(), CanoError> {
+    let counter = Arc::new(TaskCounter::default());
+
+    let workflow = Workflow::bare()
+        .register(Step::Start, DoWork)
+        .add_exit_state(Step::Done)
+        .with_observer(counter.clone());
+
+    workflow.orchestrate(Step::Start).await?;
+    assert_eq!(counter.0.load(Ordering::Relaxed), 1);
+    Ok(())
+}
 ```
 <hr class="section-divider">
 
@@ -213,9 +217,12 @@ impl WorkflowObserver for ChannelObserver {
     }
 }
 
-let (tx, _rx) = channel();
-let observer: std::sync::Arc<dyn WorkflowObserver> =
-    std::sync::Arc::new(ChannelObserver { tx });
+fn main() {
+    let (tx, _rx) = channel();
+    let observer: std::sync::Arc<dyn WorkflowObserver> =
+        std::sync::Arc::new(ChannelObserver { tx });
+    let _ = observer;
+}
 ```
 <hr class="section-divider">
 
@@ -246,10 +253,16 @@ impl DoWork {
     }
 }
 
-Workflow::bare()
-    .register(Step::Start, DoWork)
-    .add_exit_state(Step::Done)
-    .with_observer(Arc::new(TracingObserver::new()))
+#[tokio::main]
+async fn main() -> Result<(), CanoError> {
+    let workflow = Workflow::bare()
+        .register(Step::Start, DoWork)
+        .add_exit_state(Step::Done)
+        .with_observer(Arc::new(TracingObserver::new()));
+
+    workflow.orchestrate(Step::Start).await?;
+    Ok(())
+}
 ```
 
 <p>It emits <strong>events, not spans</strong> — it does not reproduce the nested span tree the
@@ -322,17 +335,20 @@ checks sequentially.
 use cano::prelude::*;
 
 // PrimaryDb and ReadReplica are Resource impls (see ReadReplica above).
-let resources: Resources = Resources::new()
-    .insert("db", PrimaryDb)
-    .insert("replica", ReadReplica);
-
-for (key, status) in resources.check_all_health().await {
-    println!("{key}: {status:?}");
-}
+#[tokio::main]
+async fn main() {
+    let resources: Resources = Resources::new()
+        .insert("db", PrimaryDb)
+        .insert("replica", ReadReplica);
+
+    for (key, status) in resources.check_all_health().await {
+        println!("{key}: {status:?}");
+    }
 
-match resources.aggregate_health().await {
-    HealthStatus::Healthy => println!("all good"),
-    other => println!("attention needed: {other:?}"),
+    match resources.aggregate_health().await {
+        HealthStatus::Healthy => println!("all good"),
+        other => println!("attention needed: {other:?}"),
+    }
 }
 ```
 
@@ -395,14 +411,18 @@ impl FlakyLoad {
     }
 }
 
-let observer = Arc::new(PrintingObserver::default());
+#[tokio::main]
+async fn main() -> Result<(), CanoError> {
+    let observer = Arc::new(PrintingObserver::default());
 
-let workflow = Workflow::bare()
-    .register(Step::Load, FlakyLoad { remaining_failures: Arc::new(AtomicUsize::new(2)) })
-    .add_exit_state(Step::Done)
-    .with_observer(observer.clone());
+    let workflow = Workflow::bare()
+        .register(Step::Load, FlakyLoad { remaining_failures: Arc::new(AtomicUsize::new(2)) })
+        .add_exit_state(Step::Done)
+        .with_observer(observer.clone());
 
-workflow.orchestrate(Step::Load).await?;
-assert_eq!(observer.failures.load(Ordering::Relaxed), 0);
+    workflow.orchestrate(Step::Load).await?;
+    assert_eq!(observer.failures.load(Ordering::Relaxed), 0);
+    Ok(())
+}
 ```
 </div>

docs/content/recovery/_index.md

@@ -74,16 +74,20 @@ impl WorkTask {
     }
 }
 
-let checkpoint_store = Arc::new(RedbCheckpointStore::new("workflow.redb")?);
-
-let workflow = Workflow::bare()
-    .register(Step::Start, StartTask)
-    .register(Step::Work, WorkTask)
-    .add_exit_state(Step::Done)
-    .with_checkpoint_store(checkpoint_store)
-    .with_workflow_id("run-42");
-
-workflow.orchestrate(Step::Start).await?;
+#[tokio::main]
+async fn main() -> Result<(), CanoError> {
+    let checkpoint_store = Arc::new(RedbCheckpointStore::new("workflow.redb")?);
+
+    let workflow = Workflow::bare()
+        .register(Step::Start, StartTask)
+        .register(Step::Work, WorkTask)
+        .add_exit_state(Step::Done)
+        .with_checkpoint_store(checkpoint_store)
+        .with_workflow_id("run-42");
+
+    workflow.orchestrate(Step::Start).await?;
+    Ok(())
+}
 ```
 <hr class="section-divider">
 
@@ -161,16 +165,20 @@ use cano::prelude::*;
 use cano::RedbCheckpointStore;
 use std::sync::Arc;
 
-let checkpoint_store = Arc::new(RedbCheckpointStore::new("workflow.redb")?);
-let workflow = Workflow::bare()
-    .register(Step::Start, StartTask)
-    .register(Step::Work, WorkTask)
-    .add_exit_state(Step::Done)
-    .with_checkpoint_store(checkpoint_store);
-
-// Some earlier process crashed mid-run; pick up where it left off.
-let final_state = workflow.resume_from("run-42").await?;
-assert_eq!(final_state, Step::Done);
+#[tokio::main]
+async fn main() -> Result<(), CanoError> {
+    let checkpoint_store = Arc::new(RedbCheckpointStore::new("workflow.redb")?);
+    let workflow = Workflow::bare()
+        .register(Step::Start, StartTask)
+        .register(Step::Work, WorkTask)
+        .add_exit_state(Step::Done)
+        .with_checkpoint_store(checkpoint_store);
+
+    // Some earlier process crashed mid-run; pick up where it left off.
+    let final_state = workflow.resume_from("run-42").await?;
+    assert_eq!(final_state, Step::Done);
+    Ok(())
+}
 ```
 
 <p>
@@ -414,27 +422,31 @@ impl FinalizeTask {
     }
 }
 
-let checkpoint_store = Arc::new(RedbCheckpointStore::new("recovery.redb")?);
-let resources = Resources::new().insert("crash", CrashOnce::default());
-let workflow = Workflow::new(resources)
-    .register(Step::Start, StartTask)
-    .register(Step::Process, ProcessTask)
-    .register(Step::Finalize, FinalizeTask)
-    .add_exit_state(Step::Done)
-    .with_checkpoint_store(checkpoint_store.clone())
-    .with_workflow_id("demo-run");
-
-// Run 1: crashes inside ProcessTask. The Start and Process rows are already durable.
-let _ = workflow.orchestrate(Step::Start).await;
-
-// Run 2: resume — re-runs ProcessTask (now it succeeds) and finishes at Done.
-let final_state = workflow.resume_from("demo-run").await?;
-assert_eq!(final_state, Step::Done);
-
-// The append-only log: Start, Process (crash), Process (re-run), Finalize, Done —
-// all RowKind::StateEntry here, since this workflow has no compensatable or stepped states.
-for row in checkpoint_store.load_run("demo-run").await? {
-    println!("#{} {:?} {}  {}", row.sequence, row.kind, row.state, row.task_id);
+#[tokio::main]
+async fn main() -> Result<(), CanoError> {
+    let checkpoint_store = Arc::new(RedbCheckpointStore::new("recovery.redb")?);
+    let resources = Resources::new().insert("crash", CrashOnce::default());
+    let workflow = Workflow::new(resources)
+        .register(Step::Start, StartTask)
+        .register(Step::Process, ProcessTask)
+        .register(Step::Finalize, FinalizeTask)
+        .add_exit_state(Step::Done)
+        .with_checkpoint_store(checkpoint_store.clone())
+        .with_workflow_id("demo-run");
+
+    // Run 1: crashes inside ProcessTask. The Start and Process rows are already durable.
+    let _ = workflow.orchestrate(Step::Start).await;
+
+    // Run 2: resume — re-runs ProcessTask (now it succeeds) and finishes at Done.
+    let final_state = workflow.resume_from("demo-run").await?;
+    assert_eq!(final_state, Step::Done);
+
+    // The append-only log: Start, Process (crash), Process (re-run), Finalize, Done —
+    // all RowKind::StateEntry here, since this workflow has no compensatable or stepped states.
+    for row in checkpoint_store.load_run("demo-run").await? {
+        println!("#{} {:?} {}  {}", row.sequence, row.kind, row.state, row.task_id);
+    }
+    Ok(())
 }
 ```
 </div>

docs/content/saga/_index.md

@@ -316,16 +316,19 @@ impl ShipOrder {
     }
 }
 
-let workflow = Workflow::bare()
-    .register_with_compensation(Step::Reserve, ReserveInventory)
-    .register(Step::Validate, ValidateOrder)              // plain — no compensation
-    .register_with_compensation(Step::Charge, ChargeCard)
-    .register(Step::Ship, ShipOrder)                      // plain — and it fails
-    .add_exit_state(Step::Done);
-
-match workflow.orchestrate(Step::Reserve).await {
-    Ok(state) => println!("completed at {state:?}"),
-    Err(error) => println!("failed, rolled back: {error}"), // "courier unavailable" — the original error
+#[tokio::main]
+async fn main() {
+    let workflow = Workflow::bare()
+        .register_with_compensation(Step::Reserve, ReserveInventory)
+        .register(Step::Validate, ValidateOrder)              // plain — no compensation
+        .register_with_compensation(Step::Charge, ChargeCard)
+        .register(Step::Ship, ShipOrder)                      // plain — and it fails
+        .add_exit_state(Step::Done);
+
+    match workflow.orchestrate(Step::Reserve).await {
+        Ok(state) => println!("completed at {state:?}"),
+        Err(error) => println!("failed, rolled back: {error}"), // "courier unavailable" — the original error
+    }
 }
 ```
 </div>