[actor] Introduce Actor SDK

.github/workflows/publish.yml

@@ -25,6 +25,11 @@ jobs:
       continue-on-error: true
       env:
         CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+    - name: Publish actor-macros
+      run: cargo publish --manifest-path actor/macros/Cargo.toml
+      continue-on-error: true
+      env:
+        CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
     - name: Publish conformance-macros
       run: cargo publish --manifest-path conformance/macros/Cargo.toml
       continue-on-error: true
@@ -70,6 +75,11 @@ jobs:
       continue-on-error: true
       env:
         CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+    - name: Publish actor
+      run: cargo publish --manifest-path actor/Cargo.toml
+      continue-on-error: true
+      env:
+        CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
     - name: Publish storage
       run: cargo publish --manifest-path storage/Cargo.toml
       continue-on-error: true

AGENTS.md

@@ -59,6 +59,34 @@ _More primitives can be found in the [Cargo.toml](Cargo.toml) file (anything wit
 - **log** (`examples/log`): Commit to a secret log and agree to its hash.
 - **sync** (`examples/sync`): Synchronize state between a server and client.
 
+### Actor Patterns
+
+Use the `actor` crate (`commonware-actor`) for actor-based concurrency instead of manually writing `select!` loops and custom mailbox definitions. The `ingress!` macro generates typed mailboxes, message enums, and convenience methods from a declarative specification. Pair it with `ServiceBuilder` to wire up the actor service loop. See the `actor` crate README and docs for full details.
+
+```rust
+use commonware_actor::{ingress, service::ServiceBuilder, Actor};
+
+// 1. Declare the mailbox
+ingress! {
+    MyMailbox,
+    pub tell DoWork { payload: Vec<u8> };
+    pub ask GetStatus -> String;
+}
+
+// 2. Implement the Actor trait (type Mailbox, Ingress, Snapshot, on_read_only, on_read_write, ...)
+
+// 3. Build and start
+let (mut mailbox, service) = ServiceBuilder::new(my_actor)
+    .build(context.with_label("my-actor"));
+service.start();
+```
+
+Key concepts:
+- `tell`: fire-and-forget. `ask`: request/response (read-only by default, `ask read_write` for mutable). `subscribe`: enqueue and get a `oneshot::Receiver`.
+- Read-only handlers run concurrently on snapshots; read-write handlers run serially.
+- Use `on_external` to translate non-mailbox events (timers, channels) into ingress messages.
+- Use `ServiceBuilder::with_lane(...)` for priority lanes (e.g., control vs data).
+
 ### Key Design Principles
 
 1. **The Simpler The Better**: Code should look obviously correct and contain the minimum features necessary to achieve a goal.

Cargo.toml

@@ -1,5 +1,7 @@
 [workspace]
 members = [
+    "actor",
+    "actor/macros",
     "broadcast",
     "codec",
     "coding",
@@ -87,6 +89,8 @@ chacha20poly1305 = { version = "0.10.1", default-features = false }
 chrono = "0.4.39"
 clap = "4.5.18"
 colored = "3.0.0"
+commonware-actor = { version = "2026.3.0", path = "actor" }
+commonware-actor-macros = { version = "2026.3.0", path = "actor/macros" }
 commonware-broadcast = { version = "2026.3.0", path = "broadcast" }
 commonware-codec = { version = "2026.3.0", path = "codec", default-features = false }
 commonware-coding = { version = "2026.3.0", path = "coding" }

README.md

@@ -12,6 +12,7 @@
 
 _Primitives are designed for deployment in adversarial environments. If you find an exploit, please refer to our [security policy](./SECURITY.md) before disclosing it publicly (an exploit may equip a malicious party to attack users of a primitive)._
 
+* [actor](./actor/README.md): Coordinate actors with messages of varying priority.
 * [broadcast](./broadcast/README.md): Disseminate data over a wide-area network.
 * [codec](./codec/README.md): Serialize structured data.
 * [coding](./coding/README.md): Encode data to enable recovery from a subset of fragments.

actor/Cargo.toml

@@ -0,0 +1,35 @@
+[package]
+name = "commonware-actor"
+edition.workspace = true
+publish = true
+version.workspace = true
+license.workspace = true
+description = "Coordinate actors with messages of varying priority."
+readme = "README.md"
+homepage.workspace = true
+repository = "https://github.com/commonwarexyz/monorepo/tree/main/actor"
+documentation = "https://docs.rs/commonware-actor"
+
+[lints]
+workspace = true
+
+[dependencies]
+commonware-actor-macros.workspace = true
+commonware-macros = { workspace = true, features = ["std"] }
+commonware-runtime.workspace = true
+commonware-utils = { workspace = true, features = ["std"] }
+futures.workspace = true
+thiserror.workspace = true
+tracing.workspace = true
+
+[lib]
+bench = false
+
+[dev-dependencies]
+criterion = { workspace = true, features = ["async"] }
+rand.workspace = true
+
+[[bench]]
+name = "actor"
+harness = false
+path = "src/benches/bench.rs"