{"owner":"slawlor","repo":"ractor","hasSkills":true,"totalSkillsCount":1,"totalTokensCount":2889,"categories":["claude-rule"],"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Mandatory Pre-Completion Checks\n\n**Before declaring any code change complete, you MUST run the following and resolve ALL errors and warnings:**\n\n```bash\n# Format all code (fix in place)\ncargo fmt --all\n\n# Run clippy with strict settings — ALL warnings must be resolved\ncargo clippy --all -- -D clippy::all -D warnings\n```\n\nDo NOT skip these steps. Do NOT declare a task done if either command produces errors or warnings. Fix any issues and re-run until clean.\n\n## Overview\n\nRactor is a pure-Rust actor framework inspired by Erlang's `gen_server`, providing lightweight actors with single-threaded message processing, supervision trees, and optional distributed clustering capabilities.\n\n## Workspace Structure\n\nThis is a Cargo workspace with multiple crates:\n- **ractor**: Core actor framework library\n- **ractor_cluster**: Distributed cluster support (experimental)\n- **ractor_cluster_derive**: Procedural macros for cluster message serialization\n- **ractor_cluster_integration_tests**: Integration tests for clustering\n- **ractor_example_entry_proc**: Example entry point procedures\n- **ractor_playground**: Playground/experimentation crate\n- **xtask**: Build/development automation tasks\n\n## Build and Test Commands\n\n### Running Tests\n\n```bash\n# Run all tests\ncargo test\n\n# Run tests for a specific package\ncargo test --package ractor\ncargo test --package ractor_cluster\n\n# Run tests with specific feature flags\ncargo test --package ractor --features cluster\ncargo test --package ractor --features async-std,message_span_propogation --no-default-features\ncargo test --package ractor --features monitors\ncargo test --package ractor --features blanket_serde\n\n# Run a specific test\ncargo test --package ractor --test <test_name>\ncargo test --package ractor <test_name>\n```\n\n### CI Feature Flag Matrix\n\nTo reproduce a CI failure locally, find the matching row and run `cargo test --package <package> <flags>`:\n\n| CI Job Name | Package | Flags |\n|---|---|---|\n| Run the default tests | ractor | *(none)* |\n| Test ractor with async-trait | ractor | `-F async-trait` |\n| Test ractor without span propogation | ractor | `--no-default-features -F tokio_runtime` |\n| Test ractor with the `cluster` feature | ractor | `-F cluster` |\n| Test ractor with the `blanket_serde` feature | ractor | `-F blanket_serde` |\n| Test ractor with async-std runtime | ractor | `--no-default-features -F async-std,message_span_propogation` |\n| Test ractor with async-std runtime but no span propagation | ractor | `--no-default-features -F async-std` |\n| Test ractor with async-std runtime and async-trait | ractor | `--no-default-features -F async-std,async-trait` |\n| Test ractor_cluster with native async traits | ractor_cluster | *(none)* |\n| Test ractor_cluster with async_trait | ractor_cluster | `-F async-trait` |\n| Test ractor with the monitor API | ractor | `-F monitors` |\n| Test ractor with output-port-v2 feature | ractor | `-F output-port-v2` |\n| Test ractor without output-port-v2 feature (explicit) | ractor | `--no-default-features -F tokio_runtime,message_span_propogation` |\n\nCI also runs: `clippy`, `rustfmt --check`, `cargo doc --lib -r`, and `cargo bench --no-run`.\n\n### Running Benchmarks\n\n```bash\n# Run benchmarks\ncargo bench -p ractor\n\n# Compile benchmarks without running\ncargo bench --no-run\n```\n\n### Linting and Formatting\n\n```bash\n# Run clippy\ncargo clippy --all -- -D clippy::all -D warnings\n\n# Run rustfmt\ncargo fmt --all\n\n# Check formatting without modifying\ncargo fmt --all -- --check\n```\n\n### Documentation\n\n```bash\n# Build documentation\ncargo doc --lib\n\n# Build documentation in release mode\ncargo doc --lib -r\n```\n\n## Architecture\n\n### Core Actor Model\n\nRactor implements the actor model with these key components:\n\n1. **Actor**: The trait defining actor behavior (`Actor` trait for `Send` actors, `ThreadLocalActor` for `!Send` actors)\n   - `pre_start`: Initialize actor state (fallible, errors returned to spawner)\n   - `post_start`: Post-initialization hook\n   - `handle`: Process incoming messages\n   - `handle_supervisor_evt`: Handle supervision events from children\n   - `post_stop`: Cleanup on shutdown\n\n2. **ActorCell**: Reference-counted primitive representing an actor's communication channels\n   - Contains message ports (signal, stop, supervision, message)\n   - Manages actor lifecycle status (Unstarted, Starting, Running, Upgrading, Draining, Stopping, Stopped)\n\n3. **ActorRef<TMessage>**: Strongly-typed wrapper over ActorCell for type-safe communication\n   - Primary interface for sending messages to actors\n   - Derefs to ActorCell for access to lower-level operations\n\n### Message Types\n\nWithout `cluster` feature: blanket `impl<T: Any + Send + Sized + 'static> Message for T` — any `Send + 'static` type works as a message with zero boilerplate.\n\nWith `cluster` feature: the blanket impl is replaced by one requiring `BytesConvertable`. For enum message types, use derive macros:\n- `#[derive(RactorMessage)]` — local-only actors (marks as non-serializable)\n- `#[derive(RactorClusterMessage)]` — remote-capable actors (generates serialization). Mark RPC variants with `#[rpc]`.\n\n`RactorClusterMessage` supports:\n- Both **tuple-style** (`Variant(A, B)`) and **struct-style** (`Variant { a: A, b: B }`) fields\n- `RpcReplyPort<T>` at **any position** in `#[rpc]` variants (detected by type scan, not position)\n- Exactly one `RpcReplyPort<T>` per `#[rpc]` variant (compile error on 0 or 2+)\n- Using `RpcReplyPort` without `#[rpc]` produces a helpful compile error\n\nThe wire format is purely positional — field names and port position don't affect serialization. Internal codegen variables are `__`-prefixed to avoid collisions with user field names.\n\nSee `ractor/src/message.rs` for trait definition and `ractor_cluster_derive/` for the proc macros.\n\n### Message Priority System\n\nMessages are processed in strict priority order (see `docs/runtime-semantics.md`):\n\n1. **Signals** (highest): Immediate termination (e.g., `Signal::Kill`)\n2. **Stop**: Graceful shutdown request\n3. **SupervisionEvent**: Child actor lifecycle notifications\n4. **Messages** (lowest): User-defined work messages\n\n### Actor State vs Self\n\n- `self`: Read-only reference containing configuration/constants (ideally empty)\n- `State`: Mutable state managed by the actor, initialized in `pre_start`\n\n### Supervision\n\n- Actors form supervision trees through linking\n- Parent actors receive `SupervisionEvent` messages on child lifecycle changes\n- Panics in message handlers are caught and reported to supervisors (unless `panic = \"abort\"`)\n- Panics in `pre_start` return errors to the spawner without starting the actor\n\n### DerivedActorRef\n\n`DerivedActorRef<TFrom>` (`ractor/src/actor/derived_actor.rs`) wraps an `ActorCell` to accept a *subset* of an actor's message type via `From` conversion. This provides interface isolation — callers only see the subset type, not the full message enum. Obtain one via `actor_ref.get_derived::<SubsetType>()`. Requires `impl From<SubsetType> for FullMsg` and `impl TryFrom<FullMsg> for SubsetType`.\n\n### Process Groups (pg)\n\n`ractor::pg` (`ractor/src/pg.rs`) provides Erlang-style named process groups — global, scope-aware collections of actors.\n\n- `pg::join(group, actors)` / `pg::leave(group, actors)` — add/remove actors (actors auto-leave on shutdown)\n- `pg::get_members(group)` / `pg::get_local_members(group)` — retrieve group members\n- `pg::which_groups()` / `pg::which_scopes()` — enumerate registered names\n- `pg::monitor(group, actor)` / `pg::demonitor(group, actor_id)` — subscribe to `SupervisionEvent::ProcessGroupChanged`\n- Scoped variants: `join_scoped`, `get_scoped_members`, `monitor_scope`, `demonitor_scope`\n\n### Named Registry\n\n`ractor::registry` (`ractor/src/registry.rs`) provides actor lookup by name.\n\n- Actors with a `Some(name)` passed to `Actor::spawn` are auto-registered and auto-unregistered on drop\n- `registry::where_is(name) -> Option<ActorCell>` — look up by name\n- `registry::registered() -> Vec<ActorName>` — list all registered names\n- With `cluster` feature: `pid_registry` sub-module adds `where_is_pid` and `PidLifecycleEvent`\n\n### Factory Pattern\n\nThe `factory` module provides worker pools for parallel job processing:\n\n- **Worker**: Trait for defining job processing logic\n- **Factory**: Manages a pool of workers with configurable routing\n- **Routing modes**: KeyPersistent, StickyQueuer, Queuer, RoundRobin, Custom\n- **Queueing**: DefaultQueue, PriorityQueue\n- Factory handles worker lifecycle, automatically restarting failed workers\n\n### Thread-Local Actors\n\nThe `thread_local` module supports `!Send` types:\n\n- Must use Tokio runtime with `rt` feature (relies on `tokio::task::LocalSet`)\n- Use `ThreadLocalActor` trait instead of `Actor`\n- Spawn with `ractor::spawn_local()` and `ThreadLocalActorSpawner`\n- State does not need to be `Send` or `Sync`\n\n## Feature Flags\n\n### ractor crate features:\n- `cluster`: Exposes functionality for `ractor_cluster` (network-distributed actors)\n- `async-std`: Use async-std runtime instead of tokio (tokio sync primitives still used)\n- `monitors`: Erlang-style monitoring API (alternative to direct linking)\n- `message_span_propogation`: Propagate tracing spans through actor messages\n- `tokio_runtime`: Tokio runtime support (default)\n- `blanket_serde`: Serde serialization support\n- `output-port-v2`: Experimental output port v2\n- `async-trait`: Use async-trait crate instead of native async traits\n\nDefault features: `tokio_runtime`, `message_span_propogation`\n\n## Cluster Support (Experimental)\n\n- **NodeServer**: Manages node connections and incoming sessions\n- **NodeSession**: Handles TCP connections, authentication, message routing, and remote actor lifecycle\n- **RemoteActor**: Untyped actor handling serialized messages from remote nodes\n- See `ractor_cluster/src/node/` for implementation and `ractor_cluster_derive/` for message serialization macros\n\n## Important Implementation Notes\n\n### Runtime Requirements\n\n- MSRV: Rust 1.85\n- Thread-local actors REQUIRE tokio runtime with `rt` feature\n- WASM support available (target `wasm32-unknown-unknown`)\n\n## Testing\n\n### Test Organization\n\n- Unit tests: `#[cfg(test)] mod tests` within each module\n- Integration tests: `ractor_cluster_integration_tests/` crate\n- Some tests require `serial_test` crate for sequential execution\n\n### Test Utilities\n\n`ractor/src/common_test.rs` provides helpers used throughout the test suite:\n\n- `periodic_check(closure, timeout)` — polls a `Fn() -> bool` every 50ms until true or timeout (then asserts)\n- `periodic_async_check(closure, timeout)` — same but for `async Fn() -> Future<Output = bool>`\n\n## Key Source Files\n\nCritical files for understanding the architecture:\n\n- `ractor/src/actor.rs`: Core Actor trait and spawn logic\n- `ractor/src/actor/actor_cell.rs`: ActorCell and ActorPortSet (message multiplexing)\n- `ractor/src/actor/actor_ref.rs`: Strongly-typed ActorRef wrapper\n- `ractor/src/actor/derived_actor.rs`: DerivedActorRef for interface isolation\n- `ractor/src/message.rs`: Message trait definition and blanket impls\n- `ractor/src/concurrency.rs`: Runtime-abstracted channel/timer primitives (tokio vs async-std)\n- `ractor/src/pg.rs`: Process groups (named actor groups)\n- `ractor/src/registry.rs`: Named actor registry\n- `ractor/src/factory.rs`: Worker pool pattern\n- `ractor/src/thread_local.rs`: Thread-local actor support\n- `ractor/src/common_test.rs`: Test utilities (`periodic_check`, `periodic_async_check`)\n- `ractor_cluster/src/node/`: NodeServer and NodeSession implementations\n- `ractor_cluster_derive/src/ir.rs`: Intermediate representation (ParsedEnum, ParsedVariant, FieldStyle, VariantKind)\n- `ractor_cluster_derive/src/parse.rs`: Parsing and validation of derive input\n- `ractor_cluster_derive/src/codegen.rs`: Code generation for `impl Message`\n- `docs/runtime-semantics.md`: Detailed runtime guarantees and edge cases\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Mandatory Pre-Completion Checks\n\n**Before declaring any code change complete, you MUST run the following and resolve ALL errors and warnings:**\n\n```bash\n# Format all code (fix in place)\ncargo fmt --all\n\n# Run clippy with strict settings — ALL warnings must be resolved\ncargo clippy --all -- -D clippy::all -D warnings\n```\n\nDo NOT skip these steps. Do NOT declare a task done if either command produces errors or warnings. Fix any issues and re-run until clean.\n\n## Overview\n\nRactor is a pure-Rust actor framework inspired by Erlang's `gen_server`, providing lightweight actors with single-threaded message processing, supervision trees, and optional distributed clustering capabilities.\n\n## Workspace Structure\n\nThis is a Cargo workspace with multiple crates:\n- **ractor**: Core actor framework library\n- **ractor_cluster**: Distributed cluster support (experimental)\n- **ractor_cluster_derive**: Procedural macros for cluster message serialization\n- **ractor_cluster_integration_tests**: Integration tests for clustering\n- **ractor_example_entry_proc**: Example entry point procedures\n- **ractor_playground**: Playground/experimentation crate\n- **xtask**: Build/development automation tasks\n\n## Build and Test Commands\n\n### Running Tests\n\n```bash\n# Run all tests\ncargo test\n\n# Run tests for a specific package\ncargo test --package ractor\ncargo test --package ractor_cluster\n\n# Run tests with specific feature flags\ncargo test --package ractor --features cluster\ncargo test --package ractor --features async-std,message_span_propogation --no-default-features\ncargo test --package ractor --features monitors\ncargo test --package ractor --features blanket_serde\n\n# Run a specific test\ncargo test --package ractor --test <test_name>\ncargo test --package ractor <test_name>\n```\n\n### CI Feature Flag Matrix\n\nTo reproduce a CI failure locally, find the matching row and run `cargo test --package <package> <flags>`:\n\n| CI Job Name | Package | Flags |\n|---|---|---|\n| Run the default tests | ractor | *(none)* |\n| Test ractor with async-trait | ractor | `-F async-trait` |\n| Test ractor without span propogation | ractor | `--no-default-features -F tokio_runtime` |\n| Test ractor with the `cluster` feature | ractor | `-F cluster` |\n| Test ractor with the `blanket_serde` feature | ractor | `-F blanket_serde` |\n| Test ractor with async-std runtime | ractor | `--no-default-features -F async-std,message_span_propogation` |\n| Test ractor with async-std runtime but no span propagation | ractor | `--no-default-features -F async-std` |\n| Test ractor with async-std runtime and async-trait | ractor | `--no-default-features -F async-std,async-trait` |\n| Test ractor_cluster with native async traits | ractor_cluster | *(none)* |\n| Test ractor_cluster with async_trait | ractor_cluster | `-F async-trait` |\n| Test ractor with the monitor API | ractor | `-F monitors` |\n| Test ractor with output-port-v2 feature | ractor | `-F output-port-v2` |\n| Test ractor without output-port-v2 feature (explicit) | ractor | `--no-default-features -F tokio_runtime,message_span_propogation` |\n\nCI also runs: `clippy`, `rustfmt --check`, `cargo doc --lib -r`, and `cargo bench --no-run`.\n\n### Running Benchmarks\n\n```bash\n# Run benchmarks\ncargo bench -p ractor\n\n# Compile benchmarks without running\ncargo bench --no-run\n```\n\n### Linting and Formatting\n\n```bash\n# Run clippy\ncargo clippy --all -- -D clippy::all -D warnings\n\n# Run rustfmt\ncargo fmt --all\n\n# Check formatting without modifying\ncargo fmt --all -- --check\n```\n\n### Documentation\n\n```bash\n# Build documentation\ncargo doc --lib\n\n# Build documentation in release mode\ncargo doc --lib -r\n```\n\n## Architecture\n\n### Core Actor Model\n\nRactor implements the actor model with these key components:\n\n1. **Actor**: The trait defining actor behavior (`Actor` trait for `Send` actors, `ThreadLocalActor` for `!Send` actors)\n   - `pre_start`: Initialize actor state (fallible, errors returned to spawner)\n   - `post_start`: Post-initialization hook\n   - `handle`: Process incoming messages\n   - `handle_supervisor_evt`: Handle supervision events from children\n   - `post_stop`: Cleanup on shutdown\n\n2. **ActorCell**: Reference-counted primitive representing an actor's communication channels\n   - Contains message ports (signal, stop, supervision, message)\n   - Manages actor lifecycle status (Unstarted, Starting, Running, Upgrading, Draining, Stopping, Stopped)\n\n3. **ActorRef<TMessage>**: Strongly-typed wrapper over ActorCell for type-safe communication\n   - Primary interface for sending messages to actors\n   - Derefs to ActorCell for access to lower-level operations\n\n### Message Types\n\nWithout `cluster` feature: blanket `impl<T: Any + Send + Sized + 'static> Message for T` — any `Send + 'static` type works as a message with zero boilerplate.\n\nWith `cluster` feature: the blanket impl is replaced by one requiring `BytesConvertable`. For enum message types, use derive macros:\n- `#[derive(RactorMessage)]` — local-only actors (marks as non-serializable)\n- `#[derive(RactorClusterMessage)]` — remote-capable actors (generates serialization). Mark RPC variants with `#[rpc]`.\n\n`RactorClusterMessage` supports:\n- Both **tuple-style** (`Variant(A, B)`) and **struct-style** (`Variant { a: A, b: B }`) fields\n- `RpcReplyPort<T>` at **any position** in `#[rpc]` variants (detected by type scan, not position)\n- Exactly one `RpcReplyPort<T>` per `#[rpc]` variant (compile error on 0 or 2+)\n- Using `RpcReplyPort` without `#[rpc]` produces a helpful compile error\n\nThe wire format is purely positional — field names and port position don't affect serialization. Internal codegen variables are `__`-prefixed to avoid collisions with user field names.\n\nSee `ractor/src/message.rs` for trait definition and `ractor_cluster_derive/` for the proc macros.\n\n### Message Priority System\n\nMessages are processed in strict priority order (see `docs/runtime-semantics.md`):\n\n1. **Signals** (highest): Immediate termination (e.g., `Signal::Kill`)\n2. **Stop**: Graceful shutdown request\n3. **SupervisionEvent**: Child actor lifecycle notifications\n4. **Messages** (lowest): User-defined work messages\n\n### Actor State vs Self\n\n- `self`: Read-only reference containing configuration/constants (ideally empty)\n- `State`: Mutable state managed by the actor, initialized in `pre_start`\n\n### Supervision\n\n- Actors form supervision trees through linking\n- Parent actors receive `SupervisionEvent` messages on child lifecycle changes\n- Panics in message handlers are caught and reported to supervisors (unless `panic = \"abort\"`)\n- Panics in `pre_start` return errors to the spawner without starting the actor\n\n### DerivedActorRef\n\n`DerivedActorRef<TFrom>` (`ractor/src/actor/derived_actor.rs`) wraps an `ActorCell` to accept a *subset* of an actor's message type via `From` conversion. This provides interface isolation — callers only see the subset type, not the full message enum. Obtain one via `actor_ref.get_derived::<SubsetType>()`. Requires `impl From<SubsetType> for FullMsg` and `impl TryFrom<FullMsg> for SubsetType`.\n\n### Process Groups (pg)\n\n`ractor::pg` (`ractor/src/pg.rs`) provides Erlang-style named process groups — global, scope-aware collections of actors.\n\n- `pg::join(group, actors)` / `pg::leave(group, actors)` — add/remove actors (actors auto-leave on shutdown)\n- `pg::get_members(group)` / `pg::get_local_members(group)` — retrieve group members\n- `pg::which_groups()` / `pg::which_scopes()` — enumerate registered names\n- `pg::monitor(group, actor)` / `pg::demonitor(group, actor_id)` — subscribe to `SupervisionEvent::ProcessGroupChanged`\n- Scoped variants: `join_scoped`, `get_scoped_members`, `monitor_scope`, `demonitor_scope`\n\n### Named Registry\n\n`ractor::registry` (`ractor/src/registry.rs`) provides actor lookup by name.\n\n- Actors with a `Some(name)` passed to `Actor::spawn` are auto-registered and auto-unregistered on drop\n- `registry::where_is(name) -> Option<ActorCell>` — look up by name\n- `registry::registered() -> Vec<ActorName>` — list all registered names\n- With `cluster` feature: `pid_registry` sub-module adds `where_is_pid` and `PidLifecycleEvent`\n\n### Factory Pattern\n\nThe `factory` module provides worker pools for parallel job processing:\n\n- **Worker**: Trait for defining job processing logic\n- **Factory**: Manages a pool of workers with configurable routing\n- **Routing modes**: KeyPersistent, StickyQueuer, Queuer, RoundRobin, Custom\n- **Queueing**: DefaultQueue, PriorityQueue\n- Factory handles worker lifecycle, automatically restarting failed workers\n\n### Thread-Local Actors\n\nThe `thread_local` module supports `!Send` types:\n\n- Must use Tokio runtime with `rt` feature (relies on `tokio::task::LocalSet`)\n- Use `ThreadLocalActor` trait instead of `Actor`\n- Spawn with `ractor::spawn_local()` and `ThreadLocalActorSpawner`\n- State does not need to be `Send` or `Sync`\n\n## Feature Flags\n\n### ractor crate features:\n- `cluster`: Exposes functionality for `ractor_cluster` (network-distributed actors)\n- `async-std`: Use async-std runtime instead of tokio (tokio sync primitives still used)\n- `monitors`: Erlang-style monitoring API (alternative to direct linking)\n- `message_span_propogation`: Propagate tracing spans through actor messages\n- `tokio_runtime`: Tokio runtime support (default)\n- `blanket_serde`: Serde serialization support\n- `output-port-v2`: Experimental output port v2\n- `async-trait`: Use async-trait crate instead of native async traits\n\nDefault features: `tokio_runtime`, `message_span_propogation`\n\n## Cluster Support (Experimental)\n\n- **NodeServer**: Manages node connections and incoming sessions\n- **NodeSession**: Handles TCP connections, authentication, message routing, and remote actor lifecycle\n- **RemoteActor**: Untyped actor handling serialized messages from remote nodes\n- See `ractor_cluster/src/node/` for implementation and `ractor_cluster_derive/` for message serialization macros\n\n## Important Implementation Notes\n\n### Runtime Requirements\n\n- MSRV: Rust 1.85\n- Thread-local actors REQUIRE tokio runtime with `rt` feature\n- WASM support available (target `wasm32-unknown-unknown`)\n\n## Testing\n\n### Test Organization\n\n- Unit tests: `#[cfg(test)] mod tests` within each module\n- Integration tests: `ractor_cluster_integration_tests/` crate\n- Some tests require `serial_test` crate for sequential execution\n\n### Test Utilities\n\n`ractor/src/common_test.rs` provides helpers used throughout the test suite:\n\n- `periodic_check(closure, timeout)` — polls a `Fn() -> bool` every 50ms until true or timeout (then asserts)\n- `periodic_async_check(closure, timeout)` — same but for `async Fn() -> Future<Output = bool>`\n\n## Key Source Files\n\nCritical files for understanding the architecture:\n\n- `ractor/src/actor.rs`: Core Actor trait and spawn logic\n- `ractor/src/actor/actor_cell.rs`: ActorCell and ActorPortSet (message multiplexing)\n- `ractor/src/actor/actor_ref.rs`: Strongly-typed ActorRef wrapper\n- `ractor/src/actor/derived_actor.rs`: DerivedActorRef for interface isolation\n- `ractor/src/message.rs`: Message trait definition and blanket impls\n- `ractor/src/concurrency.rs`: Runtime-abstracted channel/timer primitives (tokio vs async-std)\n- `ractor/src/pg.rs`: Process groups (named actor groups)\n- `ractor/src/registry.rs`: Named actor registry\n- `ractor/src/factory.rs`: Worker pool pattern\n- `ractor/src/thread_local.rs`: Thread-local actor support\n- `ractor/src/common_test.rs`: Test utilities (`periodic_check`, `periodic_async_check`)\n- `ractor_cluster/src/node/`: NodeServer and NodeSession implementations\n- `ractor_cluster_derive/src/ir.rs`: Intermediate representation (ParsedEnum, ParsedVariant, FieldStyle, VariantKind)\n- `ractor_cluster_derive/src/parse.rs`: Parsing and validation of derive input\n- `ractor_cluster_derive/src/codegen.rs`: Code generation for `impl Message`\n- `docs/runtime-semantics.md`: Detailed runtime guarantees and edge cases\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/slawlor/ractor/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Mandatory Pre-Completion Checks\n\n**Before declaring any code change complete, you MUST run the following and resolve ALL errors and warnings:**\n\n```bash\n# Format all code (fix in place)\ncargo fmt --all\n\n# Run clippy with strict settings — ALL warnings must be resolved\ncargo clippy --all -- -D clippy::all -D warnings\n```\n\nDo NOT skip these steps. Do NOT declare a task done if either command produces errors or warnings. Fix any issues and re-run until clean.\n\n## Overview\n\nRactor is a pure-Rust actor framework inspired by Erlang's `gen_server`, providing lightweight actors with single-threaded message processing, supervision trees, and optional distributed clustering capabilities.\n\n## Workspace Structure\n\nThis is a Cargo workspace with multiple crates:\n- **ractor**: Core actor framework library\n- **ractor_cluster**: Distributed cluster support (experimental)\n- **ractor_cluster_derive**: Procedural macros for cluster message serialization\n- **ractor_cluster_integration_tests**: Integration tests for clustering\n- **ractor_example_entry_proc**: Example entry point procedures\n- **ractor_playground**: Playground/experimentation crate\n- **xtask**: Build/development automation tasks\n\n## Build and Test Commands\n\n### Running Tests\n\n```bash\n# Run all tests\ncargo test\n\n# Run tests for a specific package\ncargo test --package ractor\ncargo test --package ractor_cluster\n\n# Run tests with specific feature flags\ncargo test --package ractor --features cluster\ncargo test --package ractor --features async-std,message_span_propogation --no-default-features\ncargo test --package ractor --features monitors\ncargo test --package ractor --features blanket_serde\n\n# Run a specific test\ncargo test --package ractor --test <test_name>\ncargo test --package ractor <test_name>\n```\n\n### CI Feature Flag Matrix\n\nTo reproduce a CI failure locally, find the matching row and run `cargo test --package <package> <flags>`:\n\n| CI Job Name | Package | Flags |\n|---|---|---|\n| Run the default tests | ractor | *(none)* |\n| Test ractor with async-trait | ractor | `-F async-trait` |\n| Test ractor without span propogation | ractor | `--no-default-features -F tokio_runtime` |\n| Test ractor with the `cluster` feature | ractor | `-F cluster` |\n| Test ractor with the `blanket_serde` feature | ractor | `-F blanket_serde` |\n| Test ractor with async-std runtime | ractor | `--no-default-features -F async-std,message_span_propogation` |\n| Test ractor with async-std runtime but no span propagation | ractor | `--no-default-features -F async-std` |\n| Test ractor with async-std runtime and async-trait | ractor | `--no-default-features -F async-std,async-trait` |\n| Test ractor_cluster with native async traits | ractor_cluster | *(none)* |\n| Test ractor_cluster with async_trait | ractor_cluster | `-F async-trait` |\n| Test ractor with the monitor API | ractor | `-F monitors` |\n| Test ractor with output-port-v2 feature | ractor | `-F output-port-v2` |\n| Test ractor without output-port-v2 feature (explicit) | ractor | `--no-default-features -F tokio_runtime,message_span_propogation` |\n\nCI also runs: `clippy`, `rustfmt --check`, `cargo doc --lib -r`, and `cargo bench --no-run`.\n\n### Running Benchmarks\n\n```bash\n# Run benchmarks\ncargo bench -p ractor\n\n# Compile benchmarks without running\ncargo bench --no-run\n```\n\n### Linting and Formatting\n\n```bash\n# Run clippy\ncargo clippy --all -- -D clippy::all -D warnings\n\n# Run rustfmt\ncargo fmt --all\n\n# Check formatting without modifying\ncargo fmt --all -- --check\n```\n\n### Documentation\n\n```bash\n# Build documentation\ncargo doc --lib\n\n# Build documentation in release mode\ncargo doc --lib -r\n```\n\n## Architecture\n\n### Core Actor Model\n\nRactor implements the actor model with these key components:\n\n1. **Actor**: The trait defining actor behavior (`Actor` trait for `Send` actors, `ThreadLocalActor` for `!Send` actors)\n   - `pre_start`: Initialize actor state (fallible, errors returned to spawner)\n   - `post_start`: Post-initialization hook\n   - `handle`: Process incoming messages\n   - `handle_supervisor_evt`: Handle supervision events from children\n   - `post_stop`: Cleanup on shutdown\n\n2. **ActorCell**: Reference-counted primitive representing an actor's communication channels\n   - Contains message ports (signal, stop, supervision, message)\n   - Manages actor lifecycle status (Unstarted, Starting, Running, Upgrading, Draining, Stopping, Stopped)\n\n3. **ActorRef<TMessage>**: Strongly-typed wrapper over ActorCell for type-safe communication\n   - Primary interface for sending messages to actors\n   - Derefs to ActorCell for access to lower-level operations\n\n### Message Types\n\nWithout `cluster` feature: blanket `impl<T: Any + Send + Sized + 'static> Message for T` — any `Send + 'static` type works as a message with zero boilerplate.\n\nWith `cluster` feature: the blanket impl is replaced by one requiring `BytesConvertable`. For enum message types, use derive macros:\n- `#[derive(RactorMessage)]` — local-only actors (marks as non-serializable)\n- `#[derive(RactorClusterMessage)]` — remote-capable actors (generates serialization). Mark RPC variants with `#[rpc]`.\n\n`RactorClusterMessage` supports:\n- Both **tuple-style** (`Variant(A, B)`) and **struct-style** (`Variant { a: A, b: B }`) fields\n- `RpcReplyPort<T>` at **any position** in `#[rpc]` variants (detected by type scan, not position)\n- Exactly one `RpcReplyPort<T>` per `#[rpc]` variant (compile error on 0 or 2+)\n- Using `RpcReplyPort` without `#[rpc]` produces a helpful compile error\n\nThe wire format is purely positional — field names and port position don't affect serialization. Internal codegen variables are `__`-prefixed to avoid collisions with user field names.\n\nSee `ractor/src/message.rs` for trait definition and `ractor_cluster_derive/` for the proc macros.\n\n### Message Priority System\n\nMessages are processed in strict priority order (see `docs/runtime-semantics.md`):\n\n1. **Signals** (highest): Immediate termination (e.g., `Signal::Kill`)\n2. **Stop**: Graceful shutdown request\n3. **SupervisionEvent**: Child actor lifecycle notifications\n4. **Messages** (lowest): User-defined work messages\n\n### Actor State vs Self\n\n- `self`: Read-only reference containing configuration/constants (ideally empty)\n- `State`: Mutable state managed by the actor, initialized in `pre_start`\n\n### Supervision\n\n- Actors form supervision trees through linking\n- Parent actors receive `SupervisionEvent` messages on child lifecycle changes\n- Panics in message handlers are caught and reported to supervisors (unless `panic = \"abort\"`)\n- Panics in `pre_start` return errors to the spawner without starting the actor\n\n### DerivedActorRef\n\n`DerivedActorRef<TFrom>` (`ractor/src/actor/derived_actor.rs`) wraps an `ActorCell` to accept a *subset* of an actor's message type via `From` conversion. This provides interface isolation — callers only see the subset type, not the full message enum. Obtain one via `actor_ref.get_derived::<SubsetType>()`. Requires `impl From<SubsetType> for FullMsg` and `impl TryFrom<FullMsg> for SubsetType`.\n\n### Process Groups (pg)\n\n`ractor::pg` (`ractor/src/pg.rs`) provides Erlang-style named process groups — global, scope-aware collections of actors.\n\n- `pg::join(group, actors)` / `pg::leave(group, actors)` — add/remove actors (actors auto-leave on shutdown)\n- `pg::get_members(group)` / `pg::get_local_members(group)` — retrieve group members\n- `pg::which_groups()` / `pg::which_scopes()` — enumerate registered names\n- `pg::monitor(group, actor)` / `pg::demonitor(group, actor_id)` — subscribe to `SupervisionEvent::ProcessGroupChanged`\n- Scoped variants: `join_scoped`, `get_scoped_members`, `monitor_scope`, `demonitor_scope`\n\n### Named Registry\n\n`ractor::registry` (`ractor/src/registry.rs`) provides actor lookup by name.\n\n- Actors with a `Some(name)` passed to `Actor::spawn` are auto-registered and auto-unregistered on drop\n- `registry::where_is(name) -> Option<ActorCell>` — look up by name\n- `registry::registered() -> Vec<ActorName>` — list all registered names\n- With `cluster` feature: `pid_registry` sub-module adds `where_is_pid` and `PidLifecycleEvent`\n\n### Factory Pattern\n\nThe `factory` module provides worker pools for parallel job processing:\n\n- **Worker**: Trait for defining job processing logic\n- **Factory**: Manages a pool of workers with configurable routing\n- **Routing modes**: KeyPersistent, StickyQueuer, Queuer, RoundRobin, Custom\n- **Queueing**: DefaultQueue, PriorityQueue\n- Factory handles worker lifecycle, automatically restarting failed workers\n\n### Thread-Local Actors\n\nThe `thread_local` module supports `!Send` types:\n\n- Must use Tokio runtime with `rt` feature (relies on `tokio::task::LocalSet`)\n- Use `ThreadLocalActor` trait instead of `Actor`\n- Spawn with `ractor::spawn_local()` and `ThreadLocalActorSpawner`\n- State does not need to be `Send` or `Sync`\n\n## Feature Flags\n\n### ractor crate features:\n- `cluster`: Exposes functionality for `ractor_cluster` (network-distributed actors)\n- `async-std`: Use async-std runtime instead of tokio (tokio sync primitives still used)\n- `monitors`: Erlang-style monitoring API (alternative to direct linking)\n- `message_span_propogation`: Propagate tracing spans through actor messages\n- `tokio_runtime`: Tokio runtime support (default)\n- `blanket_serde`: Serde serialization support\n- `output-port-v2`: Experimental output port v2\n- `async-trait`: Use async-trait crate instead of native async traits\n\nDefault features: `tokio_runtime`, `message_span_propogation`\n\n## Cluster Support (Experimental)\n\n- **NodeServer**: Manages node connections and incoming sessions\n- **NodeSession**: Handles TCP connections, authentication, message routing, and remote actor lifecycle\n- **RemoteActor**: Untyped actor handling serialized messages from remote nodes\n- See `ractor_cluster/src/node/` for implementation and `ractor_cluster_derive/` for message serialization macros\n\n## Important Implementation Notes\n\n### Runtime Requirements\n\n- MSRV: Rust 1.85\n- Thread-local actors REQUIRE tokio runtime with `rt` feature\n- WASM support available (target `wasm32-unknown-unknown`)\n\n## Testing\n\n### Test Organization\n\n- Unit tests: `#[cfg(test)] mod tests` within each module\n- Integration tests: `ractor_cluster_integration_tests/` crate\n- Some tests require `serial_test` crate for sequential execution\n\n### Test Utilities\n\n`ractor/src/common_test.rs` provides helpers used throughout the test suite:\n\n- `periodic_check(closure, timeout)` — polls a `Fn() -> bool` every 50ms until true or timeout (then asserts)\n- `periodic_async_check(closure, timeout)` — same but for `async Fn() -> Future<Output = bool>`\n\n## Key Source Files\n\nCritical files for understanding the architecture:\n\n- `ractor/src/actor.rs`: Core Actor trait and spawn logic\n- `ractor/src/actor/actor_cell.rs`: ActorCell and ActorPortSet (message multiplexing)\n- `ractor/src/actor/actor_ref.rs`: Strongly-typed ActorRef wrapper\n- `ractor/src/actor/derived_actor.rs`: DerivedActorRef for interface isolation\n- `ractor/src/message.rs`: Message trait definition and blanket impls\n- `ractor/src/concurrency.rs`: Runtime-abstracted channel/timer primitives (tokio vs async-std)\n- `ractor/src/pg.rs`: Process groups (named actor groups)\n- `ractor/src/registry.rs`: Named actor registry\n- `ractor/src/factory.rs`: Worker pool pattern\n- `ractor/src/thread_local.rs`: Thread-local actor support\n- `ractor/src/common_test.rs`: Test utilities (`periodic_check`, `periodic_async_check`)\n- `ractor_cluster/src/node/`: NodeServer and NodeSession implementations\n- `ractor_cluster_derive/src/ir.rs`: Intermediate representation (ParsedEnum, ParsedVariant, FieldStyle, VariantKind)\n- `ractor_cluster_derive/src/parse.rs`: Parsing and validation of derive input\n- `ractor_cluster_derive/src/codegen.rs`: Code generation for `impl Message`\n- `docs/runtime-semantics.md`: Detailed runtime guarantees and edge cases\n","isInternal":false,"tokens":2889,"sizeBytes":12014}],"systemPromptSnippet":"<yakaai_skills repo=\"slawlor/ractor\">\n<!-- File: CLAUDE.md (Tokens: ~2889 | Category: claude-rule) -->\n# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Mandatory Pre-Completion Checks\n\n**Before declaring any code change complete, you MUST run the following and resolve ALL errors and warnings:**\n\n```bash\n# Format all code (fix in place)\ncargo fmt --all\n\n# Run clippy with strict settings — ALL warnings must be resolved\ncargo clippy --all -- -D clippy::all -D warnings\n```\n\nDo NOT skip these steps. Do NOT declare a task done if either command produces errors or warnings. Fix any issues and re-run until clean.\n\n## Overview\n\nRactor is a pure-Rust actor framework inspired by Erlang's `gen_server`, providing lightweight actors with single-threaded message processing, supervision trees, and optional distributed clustering capabilities.\n\n## Workspace Structure\n\nThis is a Cargo workspace with multiple crates:\n- **ractor**: Core actor framework library\n- **ractor_cluster**: Distributed cluster support (experimental)\n- **ractor_cluster_derive**: Procedural macros for cluster message serialization\n- **ractor_cluster_integration_tests**: Integration tests for clustering\n- **ractor_example_entry_proc**: Example entry point procedures\n- **ractor_playground**: Playground/experimentation crate\n- **xtask**: Build/development automation tasks\n\n## Build and Test Commands\n\n### Running Tests\n\n```bash\n# Run all tests\ncargo test\n\n# Run tests for a specific package\ncargo test --package ractor\ncargo test --package ractor_cluster\n\n# Run tests with specific feature flags\ncargo test --package ractor --features cluster\ncargo test --package ractor --features async-std,message_span_propogation --no-default-features\ncargo test --package ractor --features monitors\ncargo test --package ractor --features blanket_serde\n\n# Run a specific test\ncargo test --package ractor --test <test_name>\ncargo test --package ractor <test_name>\n```\n\n### CI Feature Flag Matrix\n\nTo reproduce a CI failure locally, find the matching row and run `cargo test --package <package> <flags>`:\n\n| CI Job Name | Package | Flags |\n|---|---|---|\n| Run the default tests | ractor | *(none)* |\n| Test ractor with async-trait | ractor | `-F async-trait` |\n| Test ractor without span propogation | ractor | `--no-default-features -F tokio_runtime` |\n| Test ractor with the `cluster` feature | ractor | `-F cluster` |\n| Test ractor with the `blanket_serde` feature | ractor | `-F blanket_serde` |\n| Test ractor with async-std runtime | ractor | `--no-default-features -F async-std,message_span_propogation` |\n| Test ractor with async-std runtime but no span propagation | ractor | `--no-default-features -F async-std` |\n| Test ractor with async-std runtime and async-trait | ractor | `--no-default-features -F async-std,async-trait` |\n| Test ractor_cluster with native async traits | ractor_cluster | *(none)* |\n| Test ractor_cluster with async_trait | ractor_cluster | `-F async-trait` |\n| Test ractor with the monitor API | ractor | `-F monitors` |\n| Test ractor with output-port-v2 feature | ractor | `-F output-port-v2` |\n| Test ractor without output-port-v2 feature (explicit) | ractor | `--no-default-features -F tokio_runtime,message_span_propogation` |\n\nCI also runs: `clippy`, `rustfmt --check`, `cargo doc --lib -r`, and `cargo bench --no-run`.\n\n### Running Benchmarks\n\n```bash\n# Run benchmarks\ncargo bench -p ractor\n\n# Compile benchmarks without running\ncargo bench --no-run\n```\n\n### Linting and Formatting\n\n```bash\n# Run clippy\ncargo clippy --all -- -D clippy::all -D warnings\n\n# Run rustfmt\ncargo fmt --all\n\n# Check formatting without modifying\ncargo fmt --all -- --check\n```\n\n### Documentation\n\n```bash\n# Build documentation\ncargo doc --lib\n\n# Build documentation in release mode\ncargo doc --lib -r\n```\n\n## Architecture\n\n### Core Actor Model\n\nRactor implements the actor model with these key components:\n\n1. **Actor**: The trait defining actor behavior (`Actor` trait for `Send` actors, `ThreadLocalActor` for `!Send` actors)\n   - `pre_start`: Initialize actor state (fallible, errors returned to spawner)\n   - `post_start`: Post-initialization hook\n   - `handle`: Process incoming messages\n   - `handle_supervisor_evt`: Handle supervision events from children\n   - `post_stop`: Cleanup on shutdown\n\n2. **ActorCell**: Reference-counted primitive representing an actor's communication channels\n   - Contains message ports (signal, stop, supervision, message)\n   - Manages actor lifecycle status (Unstarted, Starting, Running, Upgrading, Draining, Stopping, Stopped)\n\n3. **ActorRef<TMessage>**: Strongly-typed wrapper over ActorCell for type-safe communication\n   - Primary interface for sending messages to actors\n   - Derefs to ActorCell for access to lower-level operations\n\n### Message Types\n\nWithout `cluster` feature: blanket `impl<T: Any + Send + Sized + 'static> Message for T` — any `Send + 'static` type works as a message with zero boilerplate.\n\nWith `cluster` feature: the blanket impl is replaced by one requiring `BytesConvertable`. For enum message types, use derive macros:\n- `#[derive(RactorMessage)]` — local-only actors (marks as non-serializable)\n- `#[derive(RactorClusterMessage)]` — remote-capable actors (generates serialization). Mark RPC variants with `#[rpc]`.\n\n`RactorClusterMessage` supports:\n- Both **tuple-style** (`Variant(A, B)`) and **struct-style** (`Variant { a: A, b: B }`) fields\n- `RpcReplyPort<T>` at **any position** in `#[rpc]` variants (detected by type scan, not position)\n- Exactly one `RpcReplyPort<T>` per `#[rpc]` variant (compile error on 0 or 2+)\n- Using `RpcReplyPort` without `#[rpc]` produces a helpful compile error\n\nThe wire format is purely positional — field names and port position don't affect serialization. Internal codegen variables are `__`-prefixed to avoid collisions with user field names.\n\nSee `ractor/src/message.rs` for trait definition and `ractor_cluster_derive/` for the proc macros.\n\n### Message Priority System\n\nMessages are processed in strict priority order (see `docs/runtime-semantics.md`):\n\n1. **Signals** (highest): Immediate termination (e.g., `Signal::Kill`)\n2. **Stop**: Graceful shutdown request\n3. **SupervisionEvent**: Child actor lifecycle notifications\n4. **Messages** (lowest): User-defined work messages\n\n### Actor State vs Self\n\n- `self`: Read-only reference containing configuration/constants (ideally empty)\n- `State`: Mutable state managed by the actor, initialized in `pre_start`\n\n### Supervision\n\n- Actors form supervision trees through linking\n- Parent actors receive `SupervisionEvent` messages on child lifecycle changes\n- Panics in message handlers are caught and reported to supervisors (unless `panic = \"abort\"`)\n- Panics in `pre_start` return errors to the spawner without starting the actor\n\n### DerivedActorRef\n\n`DerivedActorRef<TFrom>` (`ractor/src/actor/derived_actor.rs`) wraps an `ActorCell` to accept a *subset* of an actor's message type via `From` conversion. This provides interface isolation — callers only see the subset type, not the full message enum. Obtain one via `actor_ref.get_derived::<SubsetType>()`. Requires `impl From<SubsetType> for FullMsg` and `impl TryFrom<FullMsg> for SubsetType`.\n\n### Process Groups (pg)\n\n`ractor::pg` (`ractor/src/pg.rs`) provides Erlang-style named process groups — global, scope-aware collections of actors.\n\n- `pg::join(group, actors)` / `pg::leave(group, actors)` — add/remove actors (actors auto-leave on shutdown)\n- `pg::get_members(group)` / `pg::get_local_members(group)` — retrieve group members\n- `pg::which_groups()` / `pg::which_scopes()` — enumerate registered names\n- `pg::monitor(group, actor)` / `pg::demonitor(group, actor_id)` — subscribe to `SupervisionEvent::ProcessGroupChanged`\n- Scoped variants: `join_scoped`, `get_scoped_members`, `monitor_scope`, `demonitor_scope`\n\n### Named Registry\n\n`ractor::registry` (`ractor/src/registry.rs`) provides actor lookup by name.\n\n- Actors with a `Some(name)` passed to `Actor::spawn` are auto-registered and auto-unregistered on drop\n- `registry::where_is(name) -> Option<ActorCell>` — look up by name\n- `registry::registered() -> Vec<ActorName>` — list all registered names\n- With `cluster` feature: `pid_registry` sub-module adds `where_is_pid` and `PidLifecycleEvent`\n\n### Factory Pattern\n\nThe `factory` module provides worker pools for parallel job processing:\n\n- **Worker**: Trait for defining job processing logic\n- **Factory**: Manages a pool of workers with configurable routing\n- **Routing modes**: KeyPersistent, StickyQueuer, Queuer, RoundRobin, Custom\n- **Queueing**: DefaultQueue, PriorityQueue\n- Factory handles worker lifecycle, automatically restarting failed workers\n\n### Thread-Local Actors\n\nThe `thread_local` module supports `!Send` types:\n\n- Must use Tokio runtime with `rt` feature (relies on `tokio::task::LocalSet`)\n- Use `ThreadLocalActor` trait instead of `Actor`\n- Spawn with `ractor::spawn_local()` and `ThreadLocalActorSpawner`\n- State does not need to be `Send` or `Sync`\n\n## Feature Flags\n\n### ractor crate features:\n- `cluster`: Exposes functionality for `ractor_cluster` (network-distributed actors)\n- `async-std`: Use async-std runtime instead of tokio (tokio sync primitives still used)\n- `monitors`: Erlang-style monitoring API (alternative to direct linking)\n- `message_span_propogation`: Propagate tracing spans through actor messages\n- `tokio_runtime`: Tokio runtime support (default)\n- `blanket_serde`: Serde serialization support\n- `output-port-v2`: Experimental output port v2\n- `async-trait`: Use async-trait crate instead of native async traits\n\nDefault features: `tokio_runtime`, `message_span_propogation`\n\n## Cluster Support (Experimental)\n\n- **NodeServer**: Manages node connections and incoming sessions\n- **NodeSession**: Handles TCP connections, authentication, message routing, and remote actor lifecycle\n- **RemoteActor**: Untyped actor handling serialized messages from remote nodes\n- See `ractor_cluster/src/node/` for implementation and `ractor_cluster_derive/` for message serialization macros\n\n## Important Implementation Notes\n\n### Runtime Requirements\n\n- MSRV: Rust 1.85\n- Thread-local actors REQUIRE tokio runtime with `rt` feature\n- WASM support available (target `wasm32-unknown-unknown`)\n\n## Testing\n\n### Test Organization\n\n- Unit tests: `#[cfg(test)] mod tests` within each module\n- Integration tests: `ractor_cluster_integration_tests/` crate\n- Some tests require `serial_test` crate for sequential execution\n\n### Test Utilities\n\n`ractor/src/common_test.rs` provides helpers used throughout the test suite:\n\n- `periodic_check(closure, timeout)` — polls a `Fn() -> bool` every 50ms until true or timeout (then asserts)\n- `periodic_async_check(closure, timeout)` — same but for `async Fn() -> Future<Output = bool>`\n\n## Key Source Files\n\nCritical files for understanding the architecture:\n\n- `ractor/src/actor.rs`: Core Actor trait and spawn logic\n- `ractor/src/actor/actor_cell.rs`: ActorCell and ActorPortSet (message multiplexing)\n- `ractor/src/actor/actor_ref.rs`: Strongly-typed ActorRef wrapper\n- `ractor/src/actor/derived_actor.rs`: DerivedActorRef for interface isolation\n- `ractor/src/message.rs`: Message trait definition and blanket impls\n- `ractor/src/concurrency.rs`: Runtime-abstracted channel/timer primitives (tokio vs async-std)\n- `ractor/src/pg.rs`: Process groups (named actor groups)\n- `ractor/src/registry.rs`: Named actor registry\n- `ractor/src/factory.rs`: Worker pool pattern\n- `ractor/src/thread_local.rs`: Thread-local actor support\n- `ractor/src/common_test.rs`: Test utilities (`periodic_check`, `periodic_async_check`)\n- `ractor_cluster/src/node/`: NodeServer and NodeSession implementations\n- `ractor_cluster_derive/src/ir.rs`: Intermediate representation (ParsedEnum, ParsedVariant, FieldStyle, VariantKind)\n- `ractor_cluster_derive/src/parse.rs`: Parsing and validation of derive input\n- `ractor_cluster_derive/src/codegen.rs`: Code generation for `impl Message`\n- `docs/runtime-semantics.md`: Detailed runtime guarantees and edge cases\n</yakaai_skills>"}