Asupersync

<p align="center">
  <img src="asupersync_illustration.webp" alt="Asupersync - Spec-first, cancel-correct async for Rust" width="800">
</p>

# Asupersync

<div align="center">

<img src="asupersync_diagram.webp" alt="Asupersync Architecture - Regions, Tasks, and Quiescence" width="700">

[![License: MIT+Rider](https://img.shields.io/badge/License-MIT%2BOpenAI%2FAnthropic%20Rider-blue.svg)](./LICENSE)
[![Rust](https://img.shields.io/badge/Rust-stable_1.95%2B-orange.svg)](#minimum-supported-rust-version)
[![Status: Active Development](https://img.shields.io/badge/Status-Active%20Development-brightgreen)](https://github.com/Dicklesworthstone/asupersync)
[![Live Demo](https://img.shields.io/badge/Live_Demo-WASM_Interactive-blueviolet)](https://dicklesworthstone.github.io/asupersync/asupersync_web_demo.html)

**Spec-first, cancel-correct, capability-secure async for Rust**

<h3><a href="https://dicklesworthstone.github.io/asupersync/asupersync_web_demo.html">Try the Live Interactive WASM Demo</a></h3>

<h3>Quick Install</h3>

```bash
cargo add asupersync --git https://github.com/Dicklesworthstone/asupersync
```

</div>

---

## TL;DR

**The Problem**: Conventional executor APIs leave important lifecycle contracts
to composition and discipline. Cancellation can abandon partial effects,
detached tasks can outlive their owner, cleanup may be best-effort, and schedule
dependent failures can be difficult to reproduce.

**The Solution**: Asupersync makes its core task-ownership and runtime-tracked
effect contracts **structural rather than conventional**. Tasks are owned by
regions that close to quiescence. Cancellation is an explicit
request → drain → finalize protocol, with budgeted bounds on covered,
cooperative paths; non-cooperative code and foreign calls do not acquire a
universal shutdown bound. Runtime-managed effects require capabilities, with
host-boundary exceptions documented explicitly. The lab runtime makes
controlled schedules deterministic and replayable.

### Why Asupersync?

| Guarantee | What It Means |
|-----------|---------------|
| **No orphan tasks** | Every spawned task is owned by a region; region close waits for all children. Tasks you spawn through a `Cx` belong to that `Cx`'s region. Tasks spawned through a `RuntimeHandle` belong to the root region and are drained when the runtime shuts down. |
| **Cancellation is a request** | Cancelling a task asks it to stop. It keeps running until it reaches a cancellation point (`cx.checkpoint()` or a cancel-aware await), so it can finish its own async cleanup and return a value. A task that never reaches one is never forcibly stopped, and it holds up its region's close. |
| **Cleanup bounds** | Cleanup budgets are advisory on the production runtime: a task that keeps running past its budget is not stopped. `Runtime::shutdown_timeout` bounds how long the caller waits for teardown. |
| **No silent drops** | A channel send can reserve capacity first and commit later, so a cancelled send never loses or half-sends a message. A one-call `send()` exists for the common case. |
| **Deterministic testing** | Lab runtime: virtual time, deterministic scheduling, trace replay. The same seed reproduces the same schedule. |
| **Capability-scoped effects** | Spawning, timers and runtime-managed effects go through an explicit `Cx`. Most public I/O entry points (`TcpStream::connect`, `File::open`) take no `Cx` and check no capability today; that work is tracked as `asupersync-issue65-criticisms-kpmoy5.5`. |

These guarantees are enforced by the runtime, not by the type system. They cost
time per task: see [Measured against tokio](#measured-against-tokio).

**Experimental scheduling policy and diagnostics.** These are not guarantees:

- Adaptive cancel preemption (opt-in, `enable_adaptive_cancel_streak(true)`): a
  discounted UCB1 policy picks the cancel-streak limit from `{4, 8, 16, 32, 64}`
  at deterministic epoch boundaries. Measured against the fixed limit of 16 on
  two hosts, it did not beat it on cancel-heavy work and was 1-29% slower on
  spawn+join, yield and channel round trips, so the default is the fixed limit.
- Drain progress certificates: periodic estimates of how close a draining
  region is to quiescence, with conditional bounds. They report; they do not
  change scheduling.
- Spectral early warnings: a wait-graph spectral monitor that runs only when
  the scheduling governor is enabled (off by default).

---

## Quick Example

The attribute macro builds and drives the production runtime (a multi-thread
scheduler with the host-independent default worker count plus an on-demand
blocking pool; `#[main(flavor = "current_thread")]` and `blocking = N` adjust
both) and, when the entry future returns, drains the root region: tasks that
outlived `main` are protocol-cancelled and given `drain_ms` (default 2000) to
finish their cleanup before teardown. The first program needs no runtime
concepts:

```rust
use asupersync::main;

#[main]
async fn main() {
    print

... (truncated)