Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
271dcaa
feat!: unified start API (0.9): spawn/start/start_link/start_monitor,…
unbalancedparentheses Nov 17, 2026
8b85e75
docs: unified start in MIGRATION, GUIDE, CLAUDE.md, CHANGELOG, semant…
unbalancedparentheses Nov 17, 2026
e412b45
fix(verification): regenerate planted patches 14, 18, 19 for the unif…
unbalancedparentheses Nov 17, 2026
7720443
bench(hotpath): start the driver's actors on both sides of the 0.9 st…
unbalancedparentheses Nov 17, 2026
99b014c
chore: declare the hotpath driver's legacy-start cfg
unbalancedparentheses Nov 17, 2026
b798b8d
docs(design): unified start client mapping re-checked against the can…
unbalancedparentheses Nov 17, 2026
d9fbca9
test(start_contract): matches! for clippy
unbalancedparentheses Nov 17, 2026
ac2bacb
fix: no dead-code warnings for tasks-only start items in threads-only…
unbalancedparentheses Nov 17, 2026
7d7e7ca
fix: migrate Linux-only, simulator-only, fuzz and experiments call si…
unbalancedparentheses Nov 17, 2026
1c17e4a
fix(trace): admission and dispatch of start-recorded actors are trace…
unbalancedparentheses Nov 17, 2026
2b74e2e
fix: a start never decided (runtime drop, unwound lifecycle) fails at…
unbalancedparentheses Nov 17, 2026
8bb1877
docs(examples): index the unified start
unbalancedparentheses Nov 17, 2026
5a84db7
test(panic_safety): wait for readiness before injecting a stop (a sto…
unbalancedparentheses Nov 17, 2026
1c6ab16
feat!: an administrative stop during started() waits for it, as OTP's…
unbalancedparentheses Nov 17, 2026
58bc1ff
fix: a dispatch or thread-spawn failure after the commit kills the ch…
unbalancedparentheses Nov 17, 2026
a03cd61
fix: review #291 items 2, 5, 6, 8, 9 (trace mapping, commit lineariza…
unbalancedparentheses Nov 17, 2026
0a8ccaa
fix: init timer on the runtime clock (tasks) and one shared timer thr…
unbalancedparentheses Nov 17, 2026
ed55c53
wip: item 7 (parent exit abandons waits)
unbalancedparentheses Nov 17, 2026
22376f5
perf: read available_parallelism once per process (a third of a spawn…
unbalancedparentheses Nov 17, 2026
45560c8
Merge remote-tracking branch 'origin/main' into feat/unified-start
unbalancedparentheses Nov 17, 2026
17ef348
test(model-sync): the design-only check's example is Introspection (S…
unbalancedparentheses Nov 17, 2026
14e5088
perf: one copy of the turn body in the tasks run loop (the continuati…
unbalancedparentheses Nov 17, 2026
cafe903
perf: the tasks message loop is its own future (the start phase stays…
unbalancedparentheses Nov 17, 2026
a777a09
Merge remote-tracking branch 'origin/main' into feat/unified-start
unbalancedparentheses Nov 17, 2026
f882cec
fix: a parent's exit abandons only an undecided start wait (the answe…
unbalancedparentheses Nov 17, 2026
da477d0
test: the threads parent-kill test waits for the child's started() ex…
unbalancedparentheses Nov 17, 2026
6c5d539
fix(ci): native docs build (no tasks links from shared items); fuzz h…
unbalancedparentheses Nov 18, 2026
a75ff31
Merge remote-tracking branch 'origin/main' into feat/unified-start
unbalancedparentheses Nov 18, 2026
d9cead5
fix(fuzz): main's new oracle driver on the 0.9 start API; drop the 0.…
unbalancedparentheses Nov 18, 2026
35ddd75
Merge remote-tracking branch 'origin/main' into feat/unified-start
unbalancedparentheses Nov 21, 2026
3431311
test(planted): regenerate patch 16 against the merged monitor fence (…
unbalancedparentheses Nov 21, 2026
194b409
fix: CI on the merged main: loom harness keeps its local unit Shutdow…
unbalancedparentheses Nov 21, 2026
5484c46
fix(fuzz): a start_link child of a managed parent joins its system (0…
unbalancedparentheses Nov 21, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/verification.yml
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ jobs:
- name: Record supervisor lifecycle traces
env:
LIFECYCLE_TRACE_DIR: ${{ github.workspace }}/lifecycle-traces
run: cargo test --locked -p spawned-concurrency --features lifecycle-trace,failpoints --test supervision_trace --test cohort_trace --test tree_trace --test nested_supervision --test coverage_trace --test job_trace --test reply_trace --test disposal_trace --test lifecycle_trace --test coordinator_trace
run: cargo test --locked -p spawned-concurrency --features lifecycle-trace,failpoints --test supervision_trace --test cohort_trace --test tree_trace --test nested_supervision --test coverage_trace --test job_trace --test reply_trace --test disposal_trace --test lifecycle_trace --test start_trace --test coordinator_trace
- name: Validate traces and negative controls
run: nix run .#check-tla -- --traces-only lifecycle-traces --negative-controls
# Which model actions, projected states and transitions the recorded
Expand Down
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,6 @@ __pycache__/
# Standalone experiments crate (benchmarks/README.md)
benchmarks/experiments/target/
benchmarks/experiments/Cargo.lock

# Standalone example crates build into their own directories
examples/thread_only/target/
34 changes: 34 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,40 @@
- ROADMAP: 0.9 is now soundness and introspection; the unified start API
(G1, G2, G8) and `{shutdown, Term}` exits (G7) move into 0.9, and the
admission package is designed during 0.9.
- **Breaking: unified start API** (rank 5h, gaps G1, G2, G8; design
`docs/design/unified-start.md`). OTP's verbs in both modes: `spawn` (no
wait), `start`, `start_link(&ctx)` and `start_monitor(&ctx)` (wait for
`started()` and answer `Started`, `Ignored` or a `StartError` after the
child's publication), `with_options(StartOptions)`. `started()` may fail:
it returns `()`, `Result<(), E>`, `Result<Init<Self>, E>` or `Init<Self>`
(`ready`, `continue_with`, `error`, `stop`, `ignore`), resolved by the
design's precedence table; no failed start runs `stopped()` (also not
after `ctx.stop()` in `started()`, now `Init::stop`; a behaviour change);
an administrative stop during `started()` waits for it and runs
`stopped()`, as OTP's `gen_server:stop`. A parent killed (or hit by an
untrapped signal) while it waits for a `start_link`/`start_monitor` stops
waiting at once (`ParentExited`), as OTP's caller dies without waiting
for `init/1`. A dispatch or thread-spawn failure after the commit kills
the child (`InitExited { Killed }`) instead of a stage-1 error. The init
timer runs on the runtime clock in tasks mode (virtual under the
simulator) and on one shared thread in threads mode. `registry::register_owned`
takes the holder's `ChildHandle` (for `AlreadyStarted { existing }`). Stage 1 is one
atomic commit (group admission, the parent's link or monitor, the typed
`Name<A>`); a refusal is never observable. `start_link`/`start_monitor`
inherit the parent's placement. A failed start consumes a trapping
parent's `Exit` and a monitor's `Down`; a non-trapping parent still exits
on a non-`Normal` failure. `Init::continue_with` runs before any mailbox
entry. `init_timeout`, `ActorRef::ready()` for every placement,
`Starting::actor_ref()`. Removed: `start_on`, `start_with_backend`,
`start_linked`, `ExecutionGroup::start`, `SystemError::StartupFailed`;
test kit `Mock::spawn`/`spawn_with`, `TestSystem::spawn`/`start`/
`spawn_mock`/`options`. Every break is in `docs/MIGRATION.md` (0.8 to
0.9). Start.tla is now trace-validated (`StartEvent`, `TraceStart.tla`,
`tests/start_trace.rs`, 15 recorded-trace negative controls, coverage 28/28
arms); the model releases a group slot at scope completion, as the code
does. Not yet: scope ownership (S8), supervisor `ignore` and
`ChildSpec::options`.

- `model-sync`: a design-only TLA+ model (`design_only = true`: Start,
Introspection, DynamicSupervisor) stays allowlisted as TLC-only only while
no code maps to it; the PR that implements it must add its trace
Expand Down
13 changes: 10 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,10 +73,14 @@ Both provide identical Actor API. The `tasks` module has `Backend` enum: `Async`
| `Exit` / `#[exit_received]` | Bidirectional links and trapped exits (`ctx.link`, `ctx.trap_exit`) |
| `ActorSystem` / `ExecutionGroup` | Owned placement with worker budgets and ordered shutdown (v0.7) |
| `Supervisor` / `ChildSpec` / `SupervisedChild` | OneForOne, OneForAll, RestForOne and nested supervision (v0.7) |
| `ActorStart` | `spawn` (no wait), `start` / `start_link(&ctx)` / `start_monitor(&ctx)` (wait for `started()`), `with_options(opts)` (v0.9) |
| `StartOptions<A>` / `Name<A>` | Placement (`group`, `backend`, `placement_of`; link/monitor inherit the parent's), typed start-time name, `init_timeout`, `label`, `stack_size`, per-instance bounds (v0.9) |
| `Init<A>` | What `started()` returns: `ready`, `continue_with(msg)`, `error(e)`, `stop(r)`, `ignore` (also `()`, `Result`) (v0.9) |
| `Starting<A, T>` / `StartOutcome<T>` / `StartError` | A started instance's wait (`actor_ref()`, drop = abandon); `Started`/`Ignored`; stage-1 refusals and `InitFailed`/`InitExited`/`InitTimeout`, answered after publication (v0.9) |

## Actor Lifecycle

1. `started(&mut self, ctx: &Context<Self>)` - Setup before message loop
1. `started(&mut self, ctx: &Context<Self>) -> impl Into<Init<Self>>` - Setup before message loop; may fail, stop, ignore or continue. A failed start never runs `stopped()`
2. `Handler<M>::handle(&mut self, msg: M, reply: PendingReply<'_, M::Result>, ctx: &Context<Self>)` - Process messages
3. `stopped(&mut self, ctx: &Context<Self>)` - Cleanup after stop (skipped on kill or an untrapped exit signal)

Expand All @@ -85,8 +89,11 @@ Death has one point (`actor_cleanup.rs`): every caller is answered and links/mon
## Common Patterns

```rust
// Start an actor (use ActorStart trait)
let ns = NameServer::new().start();
// Start an actor (ActorStart trait; v0.9 OTP verbs)
let ns = NameServer::new().spawn(); // no wait
let ns = NameServer::new().start().await?.started().unwrap(); // waits for started()
let child = Worker::new().start_link(&ctx).await?; // linked, parent's placement
let worker = Worker::new().with_options(&group).spawn()?; // in an ExecutionGroup

// Call protocol methods directly on ActorRef
ns.add("key".into(), "value".into()).await.unwrap();
Expand Down
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ use spawned_rt::tasks as rt;

fn main() {
rt::run(async {
let ns = NameServer::new().start();
let ns = NameServer::new().spawn();

ns.add("Joe".into(), "At Home".into()).await.unwrap();

Expand Down Expand Up @@ -170,7 +170,9 @@ For developers familiar with Erlang/OTP:
| `gen_server:call/2` | `ns.find(...)` | Direct method call on ActorRef |
| `gen_server:cast/2` | `ns.notify(...)` | Direct method call (send variant) |
| `Pid` | `ActorRef<T>` | Handle to a running actor |
| `start_link/0` | `actor.start_linked(&ctx)` | Start the actor |
| `proc_lib:spawn/1` | `actor.spawn()` | Start without waiting for `started()` |
| `gen_server:start/3`, `start_link/3`, `start_monitor/3` | `actor.start()`, `actor.start_link(&ctx)`, `actor.start_monitor(&ctx)` | Start and wait for `started()` (`.await` in tasks mode) |
| `{ok, S}` / `{ok, S, {continue, C}}` / `{error, R}` / `{stop, R}` / `ignore` | `started()` returning `()`, `Init::continue_with(c)`, `Err(e)`, `Init::stop(r)`, `Init::ignore()` | Init results |
| `register/2` | `registry::register(name, ref)` | Register an actor by name |
| `whereis/1` | `registry::whereis(name)` | Look up an actor by name |

Expand Down Expand Up @@ -295,7 +297,7 @@ with virtual time, so timers and restart backoff take no wall-clock time:
```rust
#[spawned_concurrency::sim_test]
async fn find_returns_what_add_stored() {
let ns = NameServer::new().start();
let ns = NameServer::new().spawn();
ns.add("Joe".into(), "At Home".into()).await.unwrap();
assert_eq!(
ns.find("Joe".into()).await.unwrap(),
Expand Down
4 changes: 2 additions & 2 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -655,7 +655,7 @@ earlier [detailed acceptance criteria](https://github.com/lambdaclass/spawned/bl

| Idea | Released capability |
|---|---|
| ActorSystem and execution groups | Named parked async pools with explicit worker budgets, `start_on(&group)`, owned helpers, readiness and reverse teardown. Fixed native actor pools and parked Linux pinned shards are implemented; budgets exclude helper/owner/control/coordinator threads. |
| ActorSystem and execution groups | Named parked async pools with explicit worker budgets, `with_options(&group)` (0.8: `start_on`), owned helpers, readiness and reverse teardown. Fixed native actor pools and parked Linux pinned shards are implemented; budgets exclude helper/owner/control/coordinator threads. |
| Automatic supervision trees | ChildSpec factories, Permanent/Transient/Temporary, rolling restart limits, capped backoff/jitter, ordered startup and reverse shutdown. Nested specs and OneForAll/RestForOne are implemented, with actual cleanup barriers and bounded formal models/real trace checks for all three strategies and nested ownership. |
| Tokio-free synchronous builds | Disable async defaults on both crates; isolated fixture and graph CI cover protocols, lifecycle and metrics. ActorSystem/supervision remain async-only. |
| Fallible startup / readiness | Fallible startup and readiness for supervised children. The `result_on_start` branch is not the implementation; unsupervised `started()` still cannot fail. |
Expand Down Expand Up @@ -746,7 +746,7 @@ startup: OTP aborts `start_link` on any child start error, while Spawned retries
a Permanent or Transient child's failed factory, panic or startup timeout during
the first start (semantics §11; found reviewing #233). Behaviour change: extend the `Supervision`/`Cohorts` TLA+ models and their Apalache inductive checks (`BudgetBounded`) to the new rule, with a negative control for counting per child, and update the Kani restart-window proofs and the guide. |
| 5g | One exit reason when the runtime drops an actor (v0.8) | Tasks mode reports `Kill` when the runtime drops an actor; threads mode falls back to `Panic("unexpected framework panic")` for an actor that never finishes cleanup. Pick one documented reason for both modes and test it in both. |
| 5h | Unified start API (v0.9, design approved for implementation after three review rounds, PR #259) | [Design](docs/design/unified-start.md) with the `Start.tla` model (8 configurations, 40 negative controls; TLC-only until implemented) and a [client mapping](docs/design/unified-start-client-mapping.md). OTP's `start`, `start_link` and `start_monitor` wait for `started()` and answer `Started`, `Ignored` or an error after the child's publication (with the final exit reason); `spawn` does not wait. One typed `StartOptions`. `started()` may fail, ignore or continue (`Init`); a failed init never runs `stopped()`. An immutable startup commitment per instance; readiness committed by the child under the global lock order; the init timer and abandonment arbitrate through the commitment. Linked and monitored children inherit the parent's group or backend (API-review footgun 5.11); linked children in the parent's system are owned by its scope (polite Shutdown at the parent's publication, absolute composing deadlines). Supervisors keep the whole-attempt `startup_timeout`, and `ignore` keeps the spec as OTP. Shared result types with #245 and #256. Client impact: 51 mechanical sites, no behaviour change. |
| 5h | Unified start API (v0.9; design PR #259; **implementation in progress**: verbs, `StartOptions`, fallible `started()`, continuations, names, init timeout, inheritance and Start.tla trace validation in the first PR; scope ownership (S8) and supervisor `ignore` follow) | [Design](docs/design/unified-start.md) (with its implementation status and deviations) with the `Start.tla` model (8 configurations, 40 negative controls; trace-validated by `TraceStart.tla`) and a [client mapping](docs/design/unified-start-client-mapping.md). OTP's `start`, `start_link` and `start_monitor` wait for `started()` and answer `Started`, `Ignored` or an error after the child's publication (with the final exit reason); `spawn` does not wait. One typed `StartOptions`. `started()` may fail, ignore or continue (`Init`); a failed init never runs `stopped()`. An immutable startup commitment per instance; readiness committed by the child under the global lock order; the init timer and abandonment arbitrate through the commitment. Linked and monitored children inherit the parent's group or backend (API-review footgun 5.11); linked children in the parent's system are owned by its scope (polite Shutdown at the parent's publication, absolute composing deadlines). Supervisors keep the whole-attempt `startup_timeout`, and `ignore` keeps the spec as OTP. Shared result types with #245 and #256. Client impact: 51 mechanical sites, no behaviour change. |
| 6 | Test kit with `ActorRef::mock()` | **Phase A implemented** in [`spawned-test`](#testing-crate-spawned-test) (unreleased): closure-backed `Mock` actors that implement `Handler<M>` for every message, so `ActorRef<Mock>` satisfies any `#[protocol]` and replaces hand-stubbed protocol refs with no production change; recording `Probe<M>` recipients (`expect`, `expect_no_message`); bounded harness waits; fault injection (`faults::exit`, `restart_child`, mock delay/discard/crash). Unmocked messages fail loudly. **Remaining:** mocking a field typed as a concrete `ActorRef<B>` needs an `Envelope` hook that downcasts to the concrete message and yields message and reply sender (a core change, deferred); controllable time for timers; a generic idle check; core `ChildHandle::exit(reason)` would make injected exits exact (today `Panic` and `Kill` go through a linked helper, so a panic surfaces as `Panic("panic in handler: ...")`). **Client evidence:** hand-stubbed protocols in ethlambda tests (`RecordingChain` in `column_checks.rs`, also `envelope_checks.rs`, `verdict.rs`). **Research ([actor testing](docs/research/actor-testing.md)):** three gaps against Akka/Erlang kits. (1) A synchronous behavior test kit (Akka `BehaviorTestKit`): run one handler with a test `Context` and record its effects (sends, spawns, timers, stop) without a runtime; needs a core change. (2) Manual time (Akka `ManualTime`): document Tokio's `start_paused` for async actors; thread actors need the framework-owned clock, the same seam as the [simulation backend spike](#simulation-backend-spike) and `ctx.now()`, so build one clock, not two. (3) Concrete `ActorRef<B>` mocking stays deferred (actix's `Mocker` is the precedent); until then users hold protocol refs or `Recipient`s. Also: the idle check should report total deadlock Go-`checkdead` style (every actor idle, a request outstanding, no timer pending), and a replay-equivalence check for event-sourced actors ([event sourcing](docs/research/event-sourcing.md)). |
| 6b | Shared-state and abort lints in `#[actor]` | Zero runtime cost. The macro warns when an actor's fields hold shared mutable state (`Arc<Mutex<_>>`, `Arc<RwLock<_>>`, atomics behind `Arc`, `static mut`), with an opt-out attribute for deliberate cases, and a build script check warns when the profile uses `panic = "abort"`, under which a handler panic kills the process instead of one actor. Syntactic only (it cannot see sharing behind a type alias), but it catches the common pattern, including the one LLM-written code reaches for first. Erlang gap: memory isolation. |
| 7 | Request deadlock detection | **Client evidence:** requests awaited inside handlers exist (ethrex peer table), no cycle found; keep as a cheap safety net. `ActorError::WouldDeadlock` naming the cycle instead of a timeout. `ActorRef::request` takes only `&self`, so set a thread-local `CURRENT_ACTOR` only while the actor's own handler future is polled (and around the synchronous handler in thread mode); detached helpers create no edges. Keep a small wait set per actor for `join!`. Measure cost before enabling outside debug builds. **Approach chosen ([deadlock and stall detection](docs/research/deadlock-and-stall-detection.md)):** eager detection. Add a wait-for edge when a handler sends a request, walk the per-actor wait sets for a cycle, fail the request that would close it with `WouldDeadlock` naming the cycle, remove the edge on reply or timeout; a request to self fails at once (Erlang's `calling_self`). Waits on raw channels, locks or `spawn_blocking` create no edges, so it is a safety net, not a proof. Edges are exported to rank 30. |
Expand Down
9 changes: 5 additions & 4 deletions benchmarks/experiments/benches/designs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -693,10 +693,11 @@ fn main() {
"blocking" => tasks::Backend::Blocking,
_ => tasks::Backend::Thread,
};
Target::Tasks(tasks::ActorStart::start_with_backend(
Sink::new(&config, address),
backend,
))
Target::Tasks(
tasks::ActorStart::with_options(Sink::new(&config, address), backend)
.spawn()
.expect("spawn"),
)
}
"threads" => Target::Threads(threads::ActorStart::start(Sink::new(&config, address))),
"tokio" => {
Expand Down
8 changes: 4 additions & 4 deletions benchmarks/experiments/benches/lifecycle_soak.rs
Original file line number Diff line number Diff line change
Expand Up @@ -284,9 +284,9 @@ fn main() {
counts: counts.clone(),
pending: HashMap::new(),
}
.start();
.spawn();
// Initialize every owned actor worker/runtime while the caller still inherits actor CPUs.
let seed = Worker::new(counts.clone()).start();
let seed = Worker::new(counts.clone()).spawn();
runtime
.block_on(seed.request(Step {
expected: 0,
Expand Down Expand Up @@ -334,7 +334,7 @@ fn main() {
});
runtime.block_on(async {
let residents: Vec<_> = (0..idle)
.map(|_| Worker::new(counts.clone()).start())
.map(|_| Worker::new(counts.clone()).spawn())
.collect();
watched(&observer, &residents, false).await;
for a in &residents {
Expand All @@ -354,7 +354,7 @@ fn main() {
let mut expected_down = 0;
while started.elapsed() < Duration::from_secs(seconds) {
let actors: Vec<_> = (0..churn)
.map(|_| Worker::new(counts.clone()).start())
.map(|_| Worker::new(counts.clone()).spawn())
.collect();
let panic = counts.cycles.load(Ordering::Relaxed).is_multiple_of(16);
watched(&observer, &actors, panic).await;
Expand Down
2 changes: 1 addition & 1 deletion benchmarks/experiments/benches/pinned_pipeline.rs
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,7 @@ mod linux {
counts: counts.clone(),
handled: 0,
}
.start()
.spawn()
})
.collect();
actor_runtime.block_on(async {
Expand Down
2 changes: 1 addition & 1 deletion benchmarks/experiments/benches/runtime_isolation.rs
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ mod linux {
counts: counts.clone(),
handled: 0,
}
.start()
.spawn()
}
fn affine(n: usize) -> (u64, u64) {
let (mut a, mut b) = (1u64, 0u64);
Expand Down
2 changes: 1 addition & 1 deletion benchmarks/experiments/benches/workload_research.rs
Original file line number Diff line number Diff line change
Expand Up @@ -588,7 +588,7 @@ fn main() {
children: Vec::new(),
meter: meters[id].clone(),
}
.start(),
.spawn(),
);
}
let nodes: Vec<_> = nodes.into_iter().map(Option::unwrap).collect();
Expand Down
Loading
Loading