### GET Request Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/http/h1/http_client/index.html

Demonstrates how to initialize an HttpClient and perform a basic GET request to a specified URL.

```APIDOC
## GET /api

### Description
Performs a GET request using the HttpClient to the specified URL.

### Method
GET

### Request Example
```rust
let client = HttpClient::new();
let cx = Cx::for_testing();
let resp = client.get(&cx, "http://example.com/api").await?;
```

### Response
#### Success Response (200)
- **resp** (Response) - The HTTP response object containing status and body.
```

--------------------------------

### WebSocket Server Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/net/websocket/index.html

Example demonstrating how to set up a WebSocket server, accept upgrade requests, and echo received messages back to clients.

```APIDOC
## WebSocket Server Usage

### Description
This example illustrates how to create a WebSocket acceptor, handle incoming upgrade requests, and implement an echo server that sends back received messages.

### Method
`WebSocketAcceptor::new`, `acceptor.accept`, `ws.recv`, `ws.send`

### Endpoint
Listens for incoming connections on a specified protocol (e.g., "chat").

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
`request_bytes`, `tcp_stream` (provided during accept)

### Request Example
```rust
use asupersync::net::websocket::{WebSocketAcceptor, Message};

// Create acceptor
let acceptor = WebSocketAcceptor::new().protocol("chat");

// Accept upgrade request
let ws = acceptor.accept(&cx, request_bytes, tcp_stream).await?;

// Echo messages
while let Some(msg) = ws.recv(&cx).await? {
    ws.send(&cx, msg).await?;
}
```

### Response
#### Success Response (200)
Echoed messages sent back to the client.

#### Response Example
```
(No direct response example for echo, as it mirrors received messages)
```
```

--------------------------------

### SSE Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/web/sse/index.html

An example demonstrating how to create and return an SSE response using the `Sse` and `SseEvent` types from the `asupersync::web::sse` module.

```APIDOC
## Example
```rust
use asupersync::web::sse::{SseEvent, Sse};

fn handler() -> Sse {
    Sse::new(vec![
        SseEvent::default().data("hello"),
        SseEvent::default().event("ping").data("alive"),
    ])
}
```
```

--------------------------------

### WebSocket Client Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/net/websocket/index.html

Example demonstrating how to connect to a WebSocket server, send messages, and receive messages using the asupersync WebSocket client.

```APIDOC
## WebSocket Client Usage

### Description
This example shows how to establish a WebSocket connection, send text messages, and continuously receive messages from a server.

### Method
`WebSocket::connect` (for connection), `ws.send` (for sending), `ws.recv` (for receiving)

### Endpoint
`ws://example.com/chat` (example URL)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
`Message::text("Hello!")` (for sending a text message)

### Request Example
```rust
use asupersync::net::websocket::{WebSocket, Message};

// Connect to a WebSocket server
let ws = WebSocket::connect(&cx, "ws://example.com/chat").await?;

// Send a message
ws.send(&cx, Message::text("Hello!")).await?;

// Receive messages
while let Some(msg) = ws.recv(&cx).await? {
    println!("Received: {:?}", msg);
}
```

### Response
#### Success Response (200)
Messages received from the server.

#### Response Example
```
Received: Text("Welcome!")
Received: Binary(...) 
```
```

--------------------------------

### Spawn Task Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/cx/scope/struct.Scope.html

Example demonstrating how to spawn a task using `scope.spawn` and await its result using `handle.join`. The spawned task can access the capability context for tracing.

```rust
let handle = scope.spawn(&mut state, &cx, |cx| async move {
    cx.trace("Child task running");
    compute_value().await
});

let result = handle.join(&cx).await?;
```

--------------------------------

### Example Usage of EpochId

Source: https://docs.rs/asupersync/0.2.9/asupersync/epoch/struct.EpochId.html

Demonstrates basic usage of EpochId, including getting the genesis epoch, advancing to the next epoch, and checking epoch order. Requires the `asupersync` crate.

```rust
let current = EpochId::GENESIS;
let next = current.next();
assert!(current.is_before(next));
```

--------------------------------

### Saga Usage Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/remote/struct.Saga.html

Example demonstrating how to define steps and compensations within a Saga.

```APIDOC
use asupersync::remote::Saga;

let mut saga = Saga::new();

// Step 1: Create resource
saga.step(
    "create resource",
    || Ok("resource-1".to_string()),
    move || format!("deleted resource-1"),
)?;

// Step 2: Configure
saga.step("configure", || Ok(()), || "reset config".into())?;

// Complete on success
saga.complete();
```

--------------------------------

### VirtualClock - Example Usage

Source: https://docs.rs/asupersync/0.2.9/asupersync/time/struct.VirtualClock.html

Demonstrates how to use the VirtualClock for testing.

```APIDOC
### Example
```rust
use asupersync::time::{TimeSource, VirtualClock};
use asupersync::types::Time;

let clock = VirtualClock::new();
assert_eq!(clock.now(), Time::ZERO);

clock.advance(1_000_000_000); // 1 second
assert_eq!(clock.now(), Time::from_secs(1));
```
```

--------------------------------

### Usage Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/lab/dual_run/struct.DualRunHarness.html

Example demonstrating how to use the DualRunHarness to set up and run a differential test.

```APIDOC
### Usage
```rust
let result = DualRunHarness::phase1(
    "cancel.race.one_loser",
    "cancellation.race",
    "v1",
    "Race two tasks, cancel loser, verify drain",
    42,
)
.lab(|config| {
    let mut lab = LabRuntime::new(config);
    // ... run scenario ...
    make_happy_semantics()
})
.live(|seed, entropy_seed| {
    // ... run scenario on current-thread runtime ...
    make_happy_semantics()
})
.run();

assert!(result.passed());
```
```

--------------------------------

### CrashPack Usage Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/trace/crashpack/index.html

Example demonstrating how to build a CrashPack with failure information and a fingerprint.

```APIDOC
## CrashPack Usage Example

### Description
This example shows how to create a `CrashPack` using its builder, configuring it with essential details like a seed, configuration hash, failure information, and a trace fingerprint.

### Method
N/A (Code Example)

### Endpoint
N/A (Code Example)

### Parameters
N/A (Code Example)

### Request Example
N/A (Code Example)

### Response
N/A (Code Example)

### Code
```rust
use asupersync::trace::crashpack::{CrashPack, CrashPackConfig, FailureInfo, FailureOutcome};
use asupersync::types::{TaskId, RegionId, Time};

let pack = CrashPack::builder(CrashPackConfig {
    seed: 42,
    config_hash: 0xDEAD,
    ..Default::default()
})
.failure(FailureInfo {
    task: TaskId::testing_default(),
    region: RegionId::testing_default(),
    outcome: FailureOutcome::Panicked { message: "oops".to_string() },
    virtual_time: Time::from_secs(5),
})
.fingerprint(0xCAFE_BABE)
.build()
.expect("crash pack builder should have failure metadata");

assert_eq!(pack.manifest.schema_version, CRASHPACK_SCHEMA_VERSION);
```
```

--------------------------------

### Create and Start a Redis Docker Fixture

Source: https://docs.rs/asupersync/0.2.9/asupersync/test_logging/struct.DockerFixtureService.html

Instantiates a Redis Docker container, maps a host port, sets a health check command, starts the container, and waits for it to become healthy. Ensure the necessary imports and `port` variable are defined.

```rust
let mut redis = DockerFixtureService::new("redis", "redis:7-alpine")
    .with_port_map(port, 6379)
    .with_health_cmd(vec!["redis-cli", "ping"]);
redis.start()?;
wait_until_healthy(&redis, Duration::from_secs(10))?;
```

--------------------------------

### Example: Two-Phase Commit Choreography

Source: https://docs.rs/asupersync/0.2.9/asupersync/obligation/choreography/index.html

An example demonstrating the construction and validation of a two-phase commit choreography using the Asupersync DSL.

```APIDOC
## Example: Two-Phase Commit Choreography

```rust
use asupersync::obligation::choreography::*;

let protocol = GlobalProtocol::builder("two_phase_commit")
    .participant("coordinator", "saga-coordinator")
    .participant("worker", "saga-participant")
    .interaction(
        Interaction::comm("coordinator", "reserve", "ReserveMsg", "worker")
            .then(Interaction::choice(
                "coordinator",
                "commit_ready",
                Interaction::comm("coordinator", "commit", "CommitMsg", "worker")
                    .then(Interaction::end())
                    .expect("comm interactions accept continuations"),
                Interaction::comm("coordinator", "abort", "AbortMsg", "worker")
                    .then(Interaction::end())
                    .expect("comm interactions accept continuations"),
            ))
            .expect("comm interactions accept continuations"),
    )
    .build();

let errors = protocol.validate();
assert!(errors.is_empty(), "Validation errors: {errors:?}");

// Knowledge-of-choice: coordinator decides, so it must be the sender
// in the first communication after the branch. This is validated
// automatically.
assert!(protocol.is_deadlock_free());
```
```

--------------------------------

### Async File Create and Write Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/fs/index.html

Demonstrates creating a file, writing data to it, synchronizing changes, and then reading the content back asynchronously. Ensure proper error handling with `?`.

```rust
use asupersync::fs::File;

async fn example() -> std::io::Result<()> {
    // Create and write
    let mut file = File::create("test.txt").await?;
    file.write_all(b"hello").await?;
    file.sync_all().await?;
    drop(file);

    // Read back
    let mut file = File::open("test.txt").await?;
    let mut contents = String::new();
    file.read_to_string(&mut contents).await?;
    Ok(())
}
```

--------------------------------

### Get Child Names in Start Order

Source: https://docs.rs/asupersync/0.2.9/asupersync/supervision/struct.CompiledSupervisor.html

Returns a vector of child names in their deterministic start order. This order is used for supervisor startup.

```rust
pub fn child_start_order_names(&self) -> Vec<&str>
```

--------------------------------

### Get Drain Start Time

Source: https://docs.rs/asupersync/0.2.9/asupersync/server/shutdown/struct.ShutdownSignal.html

Returns the time when the drain phase began, if applicable. Returns `None` if the drain phase has not yet started.

```rust
pub fn drain_start(&self) -> Option<Time>
```

--------------------------------

### Set up and Manage WebSocket Server

Source: https://docs.rs/asupersync/0.2.9/asupersync/net/websocket/index.html

This example demonstrates how to create a WebSocket acceptor, handle incoming upgrade requests, and echo received messages back to the client. It requires Cx for asynchronous operations and the necessary request and stream context.

```rust
use asupersync::net::websocket::{WebSocketAcceptor, Message};

// Create acceptor
let acceptor = WebSocketAcceptor::new().protocol("chat");

// Accept upgrade request
let ws = acceptor.accept(&cx, request_bytes, tcp_stream).await?;

// Echo messages
while let Some(msg) = ws.recv(&cx).await? {
    ws.send(&cx, msg).await?;
}
```

--------------------------------

### Get Child Start Position

Source: https://docs.rs/asupersync/0.2.9/asupersync/supervision/struct.CompiledSupervisor.html

Retrieves the deterministic start position (rank) for a given child name. This is crucial for ordering supervisor-level determinism and restart sequencing.

```rust
pub fn child_start_pos(&self, child_name: &str) -> Option<usize>
```

--------------------------------

### Initialize and use a VirtualServer

Source: https://docs.rs/asupersync/0.2.9/asupersync/lab/http/struct.VirtualServer.html

Demonstrates creating a VirtualServer with a router and handling a request to verify the response status.

```rust
let router = Router::new()
    .route("/health", get(FnHandler::new(|| "ok")));

let server = VirtualServer::new(router);
let resp = server.handle(Request::new("GET", "/health"));
assert_eq!(resp.status.as_u16(), 200);
```

--------------------------------

### FaultConfig Example Usage

Source: https://docs.rs/asupersync/0.2.9/asupersync/runtime/reactor/lab/struct.FaultConfig.html

Example demonstrating how to use FaultConfig to inject errors, simulate connection closure, and partition tokens.

```APIDOC
## Example

```rust
use asupersync::runtime::reactor::{LabReactor, FaultConfig, Token, Interest};
use std::io;

let reactor = LabReactor::new();
let token = Token::new(1);

// Configure token to occasionally fail with connection reset
let config = FaultConfig::new()
    .with_error_probability(0.1)
    .with_error_kinds(vec![io::ErrorKind::ConnectionReset]);
reactor.set_fault_config(token, config);

// Or inject an immediate error
reactor.inject_error(token, io::ErrorKind::BrokenPipe);

// Or simulate connection close
reactor.inject_close(token);
```
```

--------------------------------

### Initialize and Validate ServerConfig

Source: https://docs.rs/asupersync/0.2.9/asupersync/config/struct.ServerConfig.html

Example showing how to create a configuration from a development profile and validate it.

```rust
let config = ServerConfig::from_profile(ServerProfile::Development);
assert!(config.validate().is_ok());
```

--------------------------------

### Create Interval with Specific Start Time and Period

Source: https://docs.rs/asupersync/0.2.9/asupersync/time/struct.Interval.html

Shows how to initialize an Interval with a specific start time and period. This example also verifies the period using the `period()` method.

```rust
use asupersync::time::Interval;
use asupersync::types::Time;
use std::time::Duration;

let interval = Interval::new(Time::from_secs(5), Duration::from_millis(100));
assert_eq!(interval.period(), Duration::from_millis(100));
```

--------------------------------

### Initialize a supervised application

Source: https://docs.rs/asupersync/0.2.9/asupersync/spork/index.html

Demonstrates building an application with a supervisor and child processes using the Spork prelude.

```rust
use asupersync::spork::prelude::*;

// Build an application with a supervisor and children
let app = AppSpec::new("my_app")
    .child(
        ChildSpec::new("worker", MyWorkerStart)
            .restart_policy(SupervisionStrategy::Restart(
                RestartConfig::default()
            ))
    )
    .start(&mut cx)
    .await?;

app.stop(&mut cx).await?;
```

--------------------------------

### Initialize WasmFetchBuilder

Source: https://docs.rs/asupersync/0.2.9/asupersync/types/wasm_abi/struct.WasmFetchBuilder.html

Starts building a fetch request. Defaults to the GET HTTP method.

```rust
pub fn new(scope: WasmHandleRef, url: impl Into<String>) -> Self
```

--------------------------------

### Initialize and use VirtualClient

Source: https://docs.rs/asupersync/0.2.9/asupersync/lab/http/struct.VirtualClient.html

Demonstrates creating a client instance and performing both single and batch requests.

```rust
let client = VirtualClient::new(&server);

// Single request
let resp = client.get("/health");

// Concurrent batch (order determined by seed)
let resps = client.get_batch(&["/a", "/b", "/c"]);
```

--------------------------------

### Get Active Race Count

Source: https://docs.rs/asupersync/0.2.9/asupersync/lab/oracle/loser_drain/struct.LoserDrainOracle.html

Returns the number of races that are currently active (i.e., have started but not yet completed).

```rust
pub fn active_race_count(&self) -> usize
```

--------------------------------

### Http1Listener Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/http/h1/listener/struct.Http1Listener.html

Demonstrates binding an Http1Listener to an address, defining a request handler, and running the listener within a runtime. This example requires a runtime to be built and managed.

```rust
use asupersync::http::h1::listener::{Http1Listener, Http1ListenerConfig};
use asupersync::http::h1::types::Response;
use asupersync::runtime::RuntimeBuilder;

let runtime = RuntimeBuilder::current_thread().build()?;
let handle = runtime.handle();
runtime.block_on(async {
    let listener = Http1Listener::bind("127.0.0.1:8080", |req| async {
        Response::new(200, "OK", b"Hello".to_vec())
    })
    .await?;

    // In another task: listener.begin_drain();
    let stats = listener.run(&handle).await?;
    Ok::<_, std::io::Error>(stats)
})?;
```

--------------------------------

### Get Available Permits

Source: https://docs.rs/asupersync/0.2.9/asupersync/combinator/bulkhead/struct.Bulkhead.html

Reports the number of currently available permits for acquiring. This indicates how many more operations can start immediately.

```rust
pub fn available(&self) -> u32
```

--------------------------------

### Server Lifecycle and Connection Management Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/server/index.html

Demonstrates the typical usage of `ShutdownSignal` and `ConnectionManager` for handling server shutdown and connection registration. Ensure the `listener.accept()` call is properly handled within the loop and that the `spawn connection handler` logic is implemented.

```rust
use asupersync::server::{ConnectionManager, ShutdownSignal};
use std::time::Duration;
use std::net::SocketAddr;

let signal = ShutdownSignal::new();
let manager = ConnectionManager::new(Some(10_000), signal.clone());

// Accept loop checks shutdown signal:
while !signal.is_shutting_down() {
    // let (stream, addr) = listener.accept().await?;
    if let Some(guard) = manager.register(addr) {
        // spawn connection handler with guard
    }
}

// Initiate graceful shutdown with 30s drain:
manager.begin_drain(Duration::from_secs(30));
manager.wait_all_closed().await;
signal.mark_stopped();

```

--------------------------------

### Get Pending Connection Count

Source: https://docs.rs/asupersync/0.2.9/asupersync/net/tcp/virtual_tcp/struct.VirtualTcpListener.html

Returns the number of connections that have been injected but not yet accepted. Useful for verifying test setup.

```rust
pub fn pending_count(&self) -> usize>
```

--------------------------------

### Token Slab Allocator Usage Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/runtime/reactor/token/index.html

Demonstrates how to use the TokenSlab to insert, get, and remove wakers mapped to compact tokens.

```APIDOC
## Token Slab Allocator Usage Example

### Description
This example shows the basic usage of the `TokenSlab` for managing wakers associated with unique tokens. It covers inserting a waker, retrieving it using its token, and removing it when no longer needed.

### Method
N/A (Illustrative Example)

### Endpoint
N/A (Illustrative Example)

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Code Example
```rust
use std::task::Waker;

// Assuming TokenSlab and SlabToken are accessible
// let mut slab = TokenSlab::new();
// let waker: Waker = /* ... obtain a waker ... */;
// let token = slab.insert(waker);

// Later, when an event arrives:
// if let Some(retrieved_waker) = slab.get(token) {
//     retrieved_waker.wake_by_ref();
// }

// When deregistering:
// slab.remove(token);
```

### Notes
- The `TokenSlab` provides O(1) allocation and deallocation.
- Each token includes a generation counter to prevent ABA problems.
```

--------------------------------

### Create and Configure RaptorQReceiver

Source: https://docs.rs/asupersync/0.2.9/asupersync/raptorq/builder/struct.RaptorQReceiverBuilder.html

Example demonstrating how to create a new RaptorQReceiverBuilder, set its configuration and source, and then build the receiver. Ensure a valid config and stream are provided.

```rust
let receiver = RaptorQReceiverBuilder::new()
    .config(config)
    .source(stream)
    .build()?;
```

--------------------------------

### NatsClient Usage Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/messaging/nats/index.html

This example demonstrates how to connect to a NATS server, publish a message, subscribe to a subject, and receive messages using the NatsClient.

```APIDOC
## NatsClient Usage Example

### Description
Demonstrates connecting to a NATS server, publishing a message, subscribing to a subject, and receiving messages.

### Method
N/A (Illustrative Example)

### Endpoint
N/A (Illustrative Example)

### Parameters
N/A (Illustrative Example)

### Request Example
N/A (Illustrative Example)

### Response
N/A (Illustrative Example)

### Code Example
```rust
let client = NatsClient::connect(cx, "nats://localhost:4222").await?;
client.publish(cx, "foo.bar", b"hello").await?;
let mut sub = client.subscribe(cx, "foo.*").await?;
let msg = sub.next(cx).await?;
```
```

--------------------------------

### Bulkhead Usage Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/combinator/bulkhead/index.html

Demonstrates how to initialize a BulkheadPolicy, create a Bulkhead instance, and acquire permits for protected operations.

```APIDOC
## Bulkhead Usage

### Description
This example demonstrates how to configure a bulkhead policy and use it to manage concurrent operations safely.

### Request Example
```rust
use asupersync::combinator::bulkhead::*;

let policy = BulkheadPolicy {
    name: "database".into(),
    max_concurrent: 10,
    max_queue: 100,
    ..Default::default()
};

let bulkhead = Bulkhead::new(policy);

if let Some(permit) = bulkhead.try_acquire(1) {
    // Execute protected operation
    // Permit automatically released on drop
} else {
    // Bulkhead full, handle rejection
}
```
```

--------------------------------

### Remove and Get Stored Future

Source: https://docs.rs/asupersync/0.2.9/asupersync/runtime/task_table/struct.TaskTable.html

Removes and returns a stored future for polling. This is a hot-path operation called at the start of each poll cycle.

```rust
pub fn remove_stored_future(&mut self, task_id: TaskId) -> Option<StoredTask>
```

--------------------------------

### Get Preservation Constraints

Source: https://docs.rs/asupersync/0.2.9/asupersync/obligation/guarded/fn.preservation_constraints.html

Call this function to retrieve the complete checklist of preservation constraints. No setup or imports are required beyond the function's scope.

```rust
pub fn preservation_constraints() -> Vec<PreservationConstraint>
```

--------------------------------

### Get All CALM Classifications

Source: https://docs.rs/asupersync/0.2.9/asupersync/obligation/calm/fn.classifications.html

Returns a static slice containing all CALM classifications for Asupersync saga operations. No setup or imports are required to use this function.

```rust
pub fn classifications() -> &'static [CalmClassification]
```

--------------------------------

### Create and Use TraceRecorder

Source: https://docs.rs/asupersync/0.2.9/asupersync/trace/recorder/index.html

Demonstrates how to initialize a TraceRecorder with metadata, record various events during execution, and finalize the trace. Ensure TraceMetadata is created with necessary information.

```rust
use asupersync::trace::recorder::TraceRecorder;
use asupersync::trace::replay::TraceMetadata;

// Create a recorder
let mut recorder = TraceRecorder::new(TraceMetadata::new(42));

// Record events during execution
recorder.record_task_scheduled(task_id, tick);
recorder.record_time_advanced(old_time, new_time);
recorder.record_rng_value(value);

// Finish and extract the trace
let trace = recorder.finish();
```

--------------------------------

### Use harness_phase macro

Source: https://docs.rs/asupersync/0.2.9/asupersync/macro.harness_phase.html

Example of using the harness_phase macro to enter a 'setup' phase in a TestHarness. Ensure harness_phase_exit is called to properly exit the phase.

```rust
harness_phase!(harness, "setup");
// ... work ...
harness_phase_exit!(harness);
```

--------------------------------

### Example Usage of JoinAll

Source: https://docs.rs/asupersync/0.2.9/asupersync/combinator/join/struct.JoinAll.html

Demonstrates how to use the join_all method to run multiple asynchronous computations concurrently and collect their results. Requires a scope and a context object.

```rust
let results = scope.join_all(cx, vec![ async { compute_a(cx).await }, async { compute_b(cx).await }, async { compute_c(cx).await }, ]).await;
```

--------------------------------

### Implement GenServer for a Counter

Source: https://docs.rs/asupersync/0.2.9/asupersync/gen_server/index.html

Example implementation of the GenServer trait for a Counter struct. Handles 'Get' and 'Add' calls, and 'Reset' casts. Requires the 'asupersync' crate.

```rust
struct Counter {
    count: u64,
}

enum Request {
    Get,
    Add(u64),
}

enum Cast {
    Reset,
}

impl GenServer for Counter {
    type Call = Request;
    type Reply = u64;
    type Cast = Cast;

    fn handle_call(&mut self, _cx: &Cx, msg: Request, reply: Reply<u64>)
        -> Pin<Box<dyn Future<Output = ()> + Send + '_>>
    {
        match msg {
            Request::Get => { let _ = reply.send(self.count); }
            Request::Add(n) => { self.count += n; let _ = reply.send(self.count); }
        }
        Box::pin(async {})
    }

    fn handle_cast(&mut self, _cx: &Cx, msg: Cast)
        -> Pin<Box<dyn Future<Output = ()> + Send + '_>>
    {
        match msg {
            Cast::Reset => { self.count = 0; }
        }
        Box::pin(async {})
    }
}
```

--------------------------------

### Get Next Repair ESI

Source: https://docs.rs/asupersync/0.2.9/asupersync/raptorq/systematic/struct.SystematicEncoder.html

Returns the next encoding symbol index (ESI) that will be emitted as a repair symbol. This starts at K and increments with each `emit_repair()` call.

```rust
pub const fn next_repair_esi(&self) -> u32
```

--------------------------------

### VirtualTcpListener Usage Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/net/tcp/virtual_tcp/struct.VirtualTcpListener.html

Demonstrates how to create a VirtualTcpListener, inject a connection, and accept it. This is useful for setting up test scenarios.

```rust
let listener = VirtualTcpListener::new("127.0.0.1:8080".parse().unwrap());

// From test code: inject a connection
let (client, server) = VirtualTcpStream::pair(
    "127.0.0.1:9000".parse().unwrap(),
    "127.0.0.1:8080".parse().unwrap(),
);
listener.inject_connection(server, "127.0.0.1:9000".parse().unwrap());

// From server code: accept the connection
let (stream, addr) = listener.accept().await?;
assert_eq!(addr, "127.0.0.1:9000".parse::<SocketAddr>().unwrap());
```

--------------------------------

### Handle Connections with serve

Source: https://docs.rs/asupersync/0.2.9/asupersync/net/tcp/traits/trait.TcpListenerExt.html

Example usage of the serve method to process incoming TCP connections sequentially.

```rust
listener.serve(|stream, addr| async move {
    println!("Connection from {}", addr);
    // Handle the connection...
}).await;
```

--------------------------------

### Log Custom Events with test_log Macro

Source: https://docs.rs/asupersync/0.2.9/asupersync/macro.test_log.html

Example usage of the test_log macro to log 'setup' and 'test' events. Ensure the logger and necessary variables are in scope.

```rust
test_log!(logger, "setup", "Creating listener on port {}", port);
test_log!(logger, "test", "Sending {} bytes", data.len());
```

--------------------------------

### Graceful Shutdown Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/signal/struct.ShutdownController.html

Demonstrates how to create a controller, subscribe to it, and trigger a shutdown signal.

```rust
use asupersync::signal::ShutdownController;

async fn run_server() {
    let controller = ShutdownController::new();
    let mut receiver = controller.subscribe();

    // Spawn a task that will receive the shutdown signal
    let handle = async move {
        receiver.wait().await;
        println!("Shutting down...");
    };

    // Later, initiate shutdown
    controller.shutdown();
}
```

--------------------------------

### Get Child Names in Stop Order

Source: https://docs.rs/asupersync/0.2.9/asupersync/supervision/struct.CompiledSupervisor.html

Returns a vector of child names in their deterministic stop/drain order, which is the reverse of the start order, matching OTP-style dependency unwinding.

```rust
pub fn child_stop_order_names(&self) -> Vec<&str>
```

--------------------------------

### Generate Unique Source ID

Source: https://docs.rs/asupersync/0.2.9/asupersync/runtime/reactor/source/fn.next_source_id.html

Call this function to get a new, unique source ID. IDs increase monotonically starting from 1. Panics if the ID counter overflows.

```rust
pub fn next_source_id() -> u64
```

--------------------------------

### Manage Application Lifecycle

Source: https://docs.rs/asupersync/0.2.9/asupersync/app/index.html

Demonstrates the standard workflow for starting, stopping, and joining an application using AppSpec and AppHandle.

```rust
AppSpec::new("my_app")
    .with_budget(budget)
    .child(child_spec)
    .start(&mut state, &cx, parent_region)
    -> Result<AppHandle, AppStartError>

handle.stop(&mut state)   // cancel root → drain → finalize → quiescence
handle.join(&state)       // poll terminal outcome of root region
```

--------------------------------

### Remove a prefix from a slice

Source: https://docs.rs/asupersync/0.2.9/asupersync/bytes/struct.BytesMut.html

Use `strip_prefix` to get a subslice with the specified prefix removed. Returns `None` if the slice does not start with the prefix. Handles empty prefixes and prefixes equal to the slice.

```rust
let v = &[10, 40, 30];
assert_eq!(v.strip_prefix(&[10]), Some(&[40, 30][..]));
assert_eq!(v.strip_prefix(&[10, 40]), Some(&[30][..]));
assert_eq!(v.strip_prefix(&[10, 40, 30]), Some(&[][..]));
assert_eq!(v.strip_prefix(&[50]), None);
assert_eq!(v.strip_prefix(&[10, 50]), None);
```

```rust
let prefix : &str = "he";
assert_eq!(b"hello".strip_prefix(prefix.as_bytes()),
           Some(b"llo".as_ref()));
```

--------------------------------

### Initialize and Use ProgressCertificate

Source: https://docs.rs/asupersync/0.2.9/asupersync/cancel/progress_certificate/index.html

Demonstrates how to initialize a `ProgressCertificate` with default configuration, feed it potential values from drain steps, and check the verdict for convergence and confidence.

```rust
use asupersync::cancel::progress_certificate::{
    ProgressCertificate,
    ProgressConfig,
    CertificateVerdict,
};

let config = ProgressConfig::default();
let mut cert = ProgressCertificate::new(config);

// Feed potential values from successive drain steps.
cert.observe(100.0);
cert.observe(80.0);
cert.observe(55.0);
cert.observe(30.0);
cert.observe(10.0);
cert.observe(0.0);

let verdict = cert.verdict();
assert!(verdict.converging);
assert!(verdict.confidence_bound > 0.95);
```

--------------------------------

### Get Canonical Session Protocol Adoption Order

Source: https://docs.rs/asupersync/0.2.9/asupersync/obligation/session_types/fn.session_protocol_adoption_specs.html

Returns a vector representing the canonical adoption order for session-typed obligation protocols. No setup or imports are required beyond the function's own scope.

```rust
pub fn session_protocol_adoption_specs() -> Vec<SessionProtocolAdoptionSpec>
```

--------------------------------

### Get Element Offset in Slice

Source: https://docs.rs/asupersync/0.2.9/asupersync/bytes/struct.Bytes.html

Calculates the index of an element reference within a slice using pointer arithmetic. Returns `None` if the element reference is not aligned with the start of an element in the slice. Does not compare elements.

```rust
let nums: &[u32] = &[1, 7, 1, 1];
let num = &nums[2];

assert_eq!(num, &1);
assert_eq!(nums.element_offset(num), Some(2));
```

```rust
let arr: &[[u32; 2]] = &[[0, 1], [2, 3]];
let flat_arr: &[u32] = arr.as_flattened();

let ok_elm: &[u32; 2] = flat_arr[0..2].try_into().unwrap();
let weird_elm: &[u32; 2] = flat_arr[1..3].try_into().unwrap();

assert_eq!(ok_elm, &[0, 1]);
assert_eq!(weird_elm, &[1, 2]);

assert_eq!(arr.element_offset(ok_elm), Some(0)); // Points to element 0
assert_eq!(arr.element_offset(weird_elm), None); // Points between element 0 and 1
```

--------------------------------

### Console Initialization

Source: https://docs.rs/asupersync/0.2.9/asupersync/console/struct.Console.html

Methods to instantiate a new Console instance with various configuration options.

```APIDOC
## Console::new()

### Description
Create a console that writes to stdout with auto-detected capabilities.

## Console::with_writer<W>(writer: W)

### Description
Create a console that writes to the provided writer with capabilities derived from that writer’s terminal status.

## Console::with_caps(writer: W, caps: Capabilities, color_mode: ColorMode)

### Description
Create a console with explicit capabilities and color mode.
```

--------------------------------

### BrowserHostApiIoCap Initialization

Source: https://docs.rs/asupersync/0.2.9/asupersync/io/cap/struct.BrowserHostApiIoCap.html

Creates a new instance of the BrowserHostApiIoCap adapter.

```APIDOC
## Constructor: new

### Description
Creates a new browser host API capability adapter.

### Parameters
- **authority** (HostApiAuthority) - Required - The authority policy to apply.
- **require_redaction_safe_diagnostics** (bool) - Required - Flag to determine if redaction-safe diagnostics are mandatory.
```

--------------------------------

### Get Type ID

Source: https://docs.rs/asupersync/0.2.9/asupersync/cx/scope/struct.Scope.html

Gets the `TypeId` of `self`.

```rust
type_id(&self) -> TypeId
```

--------------------------------

### GET Request

Source: https://docs.rs/asupersync/0.2.9/asupersync/http/h1/http_client/struct.HttpClient.html

Sends a GET request to the specified URL.

```APIDOC
## GET / (HttpClient::get)

### Description
Send a GET request to the given URL. The cx parameter participates in structured cancellation.

### Method
GET

### Parameters
#### Path Parameters
- **cx** (&Cx) - Required - Context for structured cancellation
- **url** (&str) - Required - The target URL

### Response
#### Success Response (200)
- **Response** - The HTTP response object
```

--------------------------------

### Create Budgets with Various Constraints

Source: https://docs.rs/asupersync/0.2.9/asupersync/types/budget/index.html

Examples of creating budgets using default, simple, and builder-pattern configurations.

```rust
// Unlimited budget (default)
let unlimited = Budget::unlimited();

// With specific deadline
let timed = Budget::with_deadline_secs(30);

// Builder pattern for multiple constraints
let complex = Budget::new()
    .with_deadline(Time::from_secs(30))
    .with_poll_quota(1000)
    .with_cost_quota(10_000)
    .with_priority(200);
```

--------------------------------

### WebSocketAcceptor Initialization and Configuration

Source: https://docs.rs/asupersync/0.2.9/asupersync/net/websocket/struct.WebSocketAcceptor.html

Demonstrates how to create a new WebSocketAcceptor and configure its various settings.

```APIDOC
## WebSocketAcceptor Configuration

### Description
This section covers the creation and configuration of the `WebSocketAcceptor`.

### Methods

#### `new()`
- **Description**: Creates a new acceptor with default configuration.
- **Returns**: A new `WebSocketAcceptor` instance.

#### `protocol(protocol: impl Into<String>)`
- **Description**: Adds a supported subprotocol to the acceptor.
- **Parameters**:
  - `protocol` (String) - The subprotocol to support.
- **Returns**: The modified `WebSocketAcceptor` instance.

#### `extension(extension: impl Into<String>)`
- **Description**: Adds a supported extension to the acceptor.
- **Parameters**:
  - `extension` (String) - The extension to support.
- **Returns**: The modified `WebSocketAcceptor` instance.

#### `max_frame_size(size: usize)`
- **Description**: Sets the maximum allowed frame size.
- **Parameters**:
  - `size` (usize) - The maximum frame size in bytes.
- **Returns**: The modified `WebSocketAcceptor` instance.

#### `max_message_size(size: usize)`
- **Description**: Sets the maximum allowed message size.
- **Parameters**:
  - `size` (usize) - The maximum message size in bytes.
- **Returns**: The modified `WebSocketAcceptor` instance.

#### `ping_interval(interval: Option<Duration>)`
- **Description**: Sets the interval for sending keepalive pings.
- **Parameters**:
  - `interval` (Option<Duration>) - The interval duration, or `None` to disable pings.
- **Returns**: The modified `WebSocketAcceptor` instance.

#### `close_timeout(timeout: Duration)`
- **Description**: Sets the timeout for the close handshake.
- **Parameters**:
  - `timeout` (Duration) - The duration for the close handshake timeout.
- **Returns**: The modified `WebSocketAcceptor` instance.
```

--------------------------------

### Arc<T, A> Examples

Source: https://docs.rs/asupersync/0.2.9/asupersync/combinator/circuit_breaker/type.StateChangeCallback.html

Illustrative examples of using Arc<T, A> in Rust.

```APIDOC
## Examples
```rust
use std::sync::Arc;

let five = Arc::new(5);

assert!(five >= Arc::new(5));
```
```

--------------------------------

### Arc<T, A> Examples

Source: https://docs.rs/asupersync/0.2.9/asupersync/combinator/bulkhead/type.FullCallback.html

Example usage of Arc<T, A> for shared ownership.

```APIDOC
## Examples

```rust
use std::sync::Arc;

let five = Arc::new(5);

assert!(five >= Arc::new(5));
```
```

--------------------------------

### FixtureService::start Method

Source: https://docs.rs/asupersync/0.2.9/asupersync/test_logging/trait.FixtureService.html

Starts the service. This method is required for all FixtureService implementations and returns a Result to indicate success or failure.

```rust
fn start(&mut self) -> Result<(), Box<dyn Error>>;
```

--------------------------------

### Function interval_at

Source: https://docs.rs/asupersync/0.2.9/asupersync/time/fn.interval_at.html

Creates an interval that yields at the given period, starting from `start`. Unlike `interval`, this allows specifying a start time different from now. Panics if `period` is zero.

```APIDOC
## Function interval_at

### Description
Creates an interval that yields at the given period, starting from `start`. Unlike `interval`, this allows specifying a start time different from now.

### Panics
Panics if `period` is zero.

### Example
```rust
use asupersync::time::interval_at;
use asupersync::types::Time;
use std::time::Duration;

// Start 1 second in the future
let start = Time::from_secs(1);
let mut int = interval_at(start, Duration::from_millis(100));

// First tick at start time
assert_eq!(int.tick(start), Time::from_secs(1));
```
```

--------------------------------

### Initialize and Run Lab Runtime

Source: https://docs.rs/asupersync/0.2.9/asupersync/lab/index.html

Demonstrates how to initialize the LabRuntime with a specific seed, create a root region, spawn a task, and run the scheduler until quiescent. This is useful for setting up a deterministic test environment.

```rust
use asupersync::lab::{LabConfig, LabRuntime};
use asupersync::types::Budget;

let mut runtime = LabRuntime::new(LabConfig::new(42));
let region = runtime.state.create_root_region(Budget::INFINITE);

let (task_id, _handle) = runtime
    .state
    .create_task(region, Budget::INFINITE, async { 42 })
    .expect("create task");

runtime.scheduler.lock().schedule(task_id, 0);
runtime.run_until_quiescent();
```

--------------------------------

### BuildError Variant Examples

Source: https://docs.rs/asupersync/0.2.9/asupersync/types/builder/enum.BuildError.html

Individual examples for constructing specific BuildError variants.

```rust
BuildError::MissingRequired { field: "name" }
```

```rust
BuildError::InvalidValue {
    field: "worker_threads",
    reason: "must be >= 1".to_string(),
}
```

```rust
BuildError::InvalidRange {
    field: "connections",
    min: 100,
    max: 10,
}
```

```rust
BuildError::ConflictingOptions {
    option_a: "single_threaded",
    option_b: "work_stealing",
}
```

```rust
BuildError::InvalidProbability {
    field: "cancel_probability",
    value: 1.5,
}
```

```rust
BuildError::InvalidDuration {
    field: "timeout",
    reason: "must be non-zero".to_string(),
}
```

```rust
BuildError::DependencyMissing {
    feature: "tls",
    dependency: "certificate",
}
```

--------------------------------

### Quick Start Runtime Builder

Source: https://docs.rs/asupersync/0.2.9/asupersync/runtime/index.html

Initialize the asupersync runtime with default settings using the fluent builder API. Use this for general-purpose asynchronous operations.

```rust
use asupersync::runtime::RuntimeBuilder;

let runtime = RuntimeBuilder::new().build()?;
runtime.block_on(async { /* your async work */ });
```

--------------------------------

### Sending Single GET Request

Source: https://docs.rs/asupersync/0.2.9/asupersync/lab/http/struct.VirtualClient.html

Sends a single GET request to the specified path.

```APIDOC
## GET /api/items/{id}

### Description
Retrieves details for a specific item by its ID.

### Method
GET

### Endpoint
/api/items/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the item to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the item.
- **name** (string) - The name of the item.
- **description** (string) - A description of the item.

#### Response Example
```json
{
  "id": "item-abcde",
  "name": "Example Item",
  "description": "This is a sample item."
}
```
```

--------------------------------

### Usage Example for LatencyAnalyzer

Source: https://docs.rs/asupersync/0.2.9/asupersync/plan/latency_algebra/struct.LatencyAnalyzer.html

Demonstrates how to create a LatencyAnalyzer, annotate leaf nodes with curves, and analyze a PlanDag. Ensure necessary imports are included.

```rust
use asupersync::plan::{PlanDag, latency_algebra::*};

let mut dag = PlanDag::new();
let a = dag.leaf("service_a");
let b = dag.leaf("service_b");
let joined = dag.join(vec![a, b]);
dag.set_root(joined);

let mut analyzer = LatencyAnalyzer::new();
analyzer.annotate(a, NodeCurves::new(
    ArrivalCurve::token_bucket(100.0, 50.0),
    ServiceCurve::rate_latency(200.0, 0.001),
));
analyzer.annotate(b, NodeCurves::new(
    ArrivalCurve::token_bucket(80.0, 30.0),
    ServiceCurve::rate_latency(150.0, 0.002),
));

let analysis = analyzer.analyze(&dag);
println!("{}", analysis.summary());
```

--------------------------------

### Create and Verify Event

Source: https://docs.rs/asupersync/0.2.9/asupersync/runtime/reactor/struct.Event.html

Example of creating a new Event and checking its readiness state.

```rust
use asupersync::runtime::reactor::{Event, Interest, Token};

let event = Event::new(Token::new(1), Interest::READABLE | Interest::WRITABLE);
assert!(event.is_readable());
assert!(event.is_writable());
```

--------------------------------

### get

Source: https://docs.rs/asupersync/0.2.9/asupersync/bytes/struct.Bytes.html

Safely gets a reference to an element or subslice. Returns None if the index is out of bounds.

```APIDOC
## GET /slice/get

### Description
Safely retrieves a reference to an element or a subslice from a slice. Returns `None` if the provided index is out of bounds.

### Method
GET

### Endpoint
`/slice/{index}` or `/slice/{start}..{end}`

### Parameters
#### Path Parameters
- **index** (usize or Range<usize>) - Required - The index or range of indices to access.

### Response
#### Success Response (200)
- **element/subslice** (T or &[T]) - A reference to the requested element or subslice.

#### Response Example
```json
{
  "element": 40
}
```

```json
{
  "subslice": [10, 40]
}
```
```

--------------------------------

### Serve Method

Source: https://docs.rs/asupersync/0.2.9/asupersync/grpc/server/struct.Server.html

Validates server readiness and attempts to bind to a given address.

```APIDOC
## `Server::serve()`

### Description
Validate server readiness and perform a bind-probe on the given address.
This verifies that:
  * At least one service is registered
  * The listen address parses as a socket address
  * The process can bind a listener at that address

The listener is immediately dropped after validation; request serving is provided by transport adapters layered above this core server registry.

### Method
`pub async fn serve(self, addr: &str) -> Result<(), GrpcError>`

### Parameters
#### Path Parameters
- **addr** (str) - Description: The address to bind and probe.
```

--------------------------------

### Outcome Examples

Source: https://docs.rs/asupersync/0.2.9/asupersync/types/outcome/enum.Outcome.html

Illustrative examples demonstrating the usage of the Outcome type in various scenarios.

```APIDOC
## Examples
```rust
use asupersync::Outcome;

fn parse_int(s: &str) -> Outcome<i32, &'static str> {
    s.parse::<i32>().map_err(|_| "parse error").into()
}

fn double(x: i32) -> Outcome<i32, &'static str> {
    Outcome::ok(x * 2)
}

let result = parse_int("21").and_then(double);
assert_eq!(result.unwrap(), 42);

let result = parse_int("abc").and_then(double);
assert!(result.is_err());
```
```

--------------------------------

### Example Usage of NdjsonLogger and write_artifact_bundle

Source: https://docs.rs/asupersync/0.2.9/asupersync/test_ndjson/index.html

Demonstrates setting up an NDJSON logger, logging a task spawn event, and writing an artifact bundle. Ensure necessary imports are present.

```rust
use asupersync::test_ndjson::{NdjsonLogger, write_artifact_bundle};
use asupersync::test_logging::{TestLogLevel, TestEvent, TestContext, ReproManifest};

let ctx = TestContext::new("my_test", 0xDEAD_BEEF).with_subsystem("scheduler");
let logger = NdjsonLogger::enabled(TestLogLevel::Info, Some(ctx.clone()));

logger.log(TestEvent::TaskSpawn { task_id: 1, name: Some("worker".into()) });

let manifest = ReproManifest::from_context(&ctx, true).with_env_snapshot();
let bundle = write_artifact_bundle(&manifest, Some(&logger), None).unwrap();
```

--------------------------------

### Create New TopologyExplorer

Source: https://docs.rs/asupersync/0.2.9/asupersync/lab/explorer/struct.TopologyExplorer.html

Initializes a new TopologyExplorer instance with the provided configuration. This is the entry point for setting up the exploration engine.

```rust
pub fn new(config: ExplorerConfig) -> Self>
```

--------------------------------

### ShutdownSignal - Example Usage

Source: https://docs.rs/asupersync/0.2.9/asupersync/server/shutdown/struct.ShutdownSignal.html

Example demonstrating how to use ShutdownSignal for server shutdown coordination.

```APIDOC
## ShutdownSignal - Example Usage

```rust
use asupersync::server::ShutdownSignal;
use std::time::Duration;

let signal = ShutdownSignal::new();

// In the accept loop:
if signal.is_draining() {
    break; // stop accepting
}

// Initiate shutdown with a 30-second drain period:
signal.begin_drain(Duration::from_secs(30));
```
```

--------------------------------

### Semaphore Usage Example

Source: https://docs.rs/asupersync/0.2.9/asupersync/sync/semaphore/index.html

Demonstrates how to create a Semaphore, acquire a permit, and how permits are automatically released.

```APIDOC
## Semaphore Usage Example

### Description
This example shows the basic usage of the `Semaphore` including initialization, acquiring a permit, and the automatic release of permits upon dropping.

### Method
N/A (Illustrative Example)

### Endpoint
N/A (Rust Code)

### Request Example
```rust
use asupersync::sync::Semaphore;

// Create semaphore with 10 permits
let sem = Semaphore::new(10);

// Acquire a permit (awaits until available)
let permit = sem.acquire(&cx, 1).await?;

// Permit is automatically released when dropped
drop(permit);
```

### Response
N/A (Illustrative Example)
```

--------------------------------

### Spawn and Wait for Child Process

Source: https://docs.rs/asupersync/0.2.9/asupersync/process/struct.Child.html

This example demonstrates spawning a child process and waiting for it to complete. Ensure the `Command` is configured correctly before spawning. The `wait()` method returns the exit status of the process.

```rust
let mut child = Command::new("sleep").arg("1").spawn()?;
let status = child.wait()?;
println!("Exit code: {:?}", status.code());
```

--------------------------------

### GET /btree/entry

Source: https://docs.rs/asupersync/0.2.9/asupersync/util/det_hash/struct.BTreeMap.html

Gets the given key’s corresponding entry in the map for in-place manipulation.

```APIDOC
## GET /btree/entry

### Description
Provides an entry API for the given key, allowing for conditional insertion or modification.

### Parameters
#### Query Parameters
- **key** (K) - Required - The key to retrieve an entry for.
```

--------------------------------

### AppSpec::start

Source: https://docs.rs/asupersync/0.2.9/asupersync/app/struct.AppSpec.html

Compiles, allocates a root region, and spawns the application supervisor.

```APIDOC
### pub fn start( self, state: &mut RuntimeState, cx: &Cx, parent_region: RegionId, ) -> Result<AppHandle, AppStartError>

Compile, allocate a root region, and spawn the application supervisor.
Convenience method that chains `AppSpec::compile` and `CompiledApp::start`.
```

--------------------------------

### GET / (MethodRouter)

Source: https://docs.rs/asupersync/0.2.9/asupersync/web/router/fn.get.html

Defines a method router for handling GET requests within the asupersync framework.

```APIDOC
## GET (asupersync::web::router::get)

### Description
Creates a method router configured with a GET handler.

### Method
GET

### Parameters
- **handler** (impl Handler) - Required - The handler function or closure to be executed for GET requests.
```

--------------------------------

### Start Application

Source: https://docs.rs/asupersync/0.2.9/asupersync/app/struct.AppSpec.html

Compile, allocate a root region, and spawn the application supervisor. This is a convenience method that chains `AppSpec::compile` and `CompiledApp::start`.

```rust
pub fn start(
    self,
    state: &mut RuntimeState,
    cx: &Cx,
    parent_region: RegionId,
) -> Result<AppHandle, AppStartError>
```