PicoActor.Abs 2026.1.0

PicoActor

AOT-compatible, in-memory Actor framework with Event Sourcing for .NET. Lightweight, zero-reflection, designed for agentic AI systems and workflow orchestration. Runs under NativeAOT and trimming.

English | 简体中文 | 日本語 | Español | Português | 繁體中文 | 한국어 | Français | Deutsch | Русский

Computational Model

┌─────────────────────────────────────────────────┐
│                  ActorSystem                     │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐         │
│  │ Counter │  │  Agent  │  │ Session │  ...     │
│  │ (Actor) │  │ (Actor) │  │ (Actor) │         │
│  └────┬────┘  └────┬────┘  └────┬────┘         │
│       │            │            │               │
│       ▼            ▼            ▼               │
│  ┌─────────────────────────────────────────┐    │
│  │            IEventStore                   │    │
│  │   AppendAsync / LoadAsync               │    │
│  └─────────────────────────────────────────┘    │
└─────────────────────────────────────────────────┘

Each actor owns a mailbox (in-memory Channel<Envelope>), a UUID v7 identity, and a single-threaded consumption loop. Commands are delivered via Send (fire-and-forget) or AskAsync (request-reply).

Event-Sourced actors follow Persist-then-Mutate: OnMessageAsync → RaiseEvent → Persist to IEventStore → Mutate state. State is only mutated after successful persistence — the in-memory state is always consistent with the event stream.

Why PicoActor

Quick Start

dotnet add package PicoActor

using PicoActor;
using PicoActor.Abs;

// 1. Setup
var store = new InMemoryEventStore();
var system = new ActorSystem(store);

// 2. Register actor factories
system.Register<Counter>(
    createFactory: cmd => cmd switch
    {
        CreateCounter c => new Counter(c),
        _ => throw new InvalidOperationException()
    },
    rebuildFactory: () => new Counter()
);

// 3. Create, message, stop, rebuild
var counter = await system.CreateAsync<Counter>(new CreateCounter(42));
system.Send(counter.Id, new Increment(5));
var value = await system.AskAsync<int>(counter.Id, new GetValue());
await system.StopAsync(counter.Id);
var rebuilt = await system.GetAsync<Counter>(counter.Id);

Module Details

PicoActor.Abs — Core Abstractions

Targets netstandard2.0 for maximum compatibility. Contains all interfaces and base classes.

PicoActor — Runtime

Targets net10.0, AOT-compatible.

Actor (Non-ES)

Inherit from Actor for pure in-memory operational actors.

public sealed class EchoActor : Actor
{
    protected override ValueTask<object?> OnMessageAsync(ICommand command)
        => new ValueTask<object?>(command);
}

Event-Sourced Actor

Inherit from EventSourcedActor. Override OnMessageAsync to call RaiseEvent, and Mutate to apply state changes.

public sealed class Counter : EventSourcedActor
{
    private int _value;

    public Counter(CreateCounter cmd) : base(cmd) { }
    public Counter() { }

    protected override ValueTask<object?> OnMessageAsync(ICommand command)
    {
        switch (command)
        {
            case Increment i:
                RaiseEvent(new CounterIncremented(i.Delta));
                break;
            case GetValue:
                return new ValueTask<object?>(_value);
        }
        return default;
    }

    protected override void Mutate(IDomainEvent @event)
    {
        switch (@event)
        {
            case CounterIncremented e: _value += e.Delta; break;
        }
    }
}

Persist-then-Mutate Pipeline

OnMessageAsync → RaiseEvent (record only, no state change)
              → AppendAsync (persist to IEventStore)
              → Mutate (apply events to in-memory state)
              → Reply to caller (only after success)

If AppendAsync fails, uncommitted events are discarded and Version is rolled back. The actor is not poisoned — the next message processes cleanly.

Messaging: Ask vs Send

OutputChannel

Actors broadcast ActorOutputEvent messages to external subscribers:

counter.OutputWriter = channel.Writer;
// Inside OnMessageAsync:
WriteOutput("Incremented", data: "Delta=5");

CancelTurn

Cancel long-running operations without stopping the actor:

public sealed class MyActor : Actor, ICancelable
{
    private CancellationTokenSource? _currentTurnCts;
    public void CancelCurrentTurn() => _currentTurnCts?.Cancel();

    protected override async ValueTask<object?> OnMessageAsync(ICommand command)
    {
        _currentTurnCts = CancellationTokenSource.CreateLinkedTokenSource(StopToken);
        // ... long-running work with _currentTurnCts.Token
    }
}
system.CancelTurn(actor.Id);

Spawn

Actors create child actors via System reference:

protected override async ValueTask<object?> OnMessageAsync(ICommand command)
{
    if (command is SpawnChild s)
    {
        var child = await System!.CreateAsync<Worker>(s.Cmd);
        return child.Id;
    }
    return default;
}

Module Integration

PicoDI

var container = new SvcContainer();
container.AddPicoActor();  // Registers IActorSystem + InMemoryEventStore

// Custom event store
var store = new InMemoryEventStore();
container.AddPicoActor(store);

// From PicoCfg
var cfg = CfgBind.Bind<ActorConfig>(configuration, "Actor");
container.AddPicoActor(cfg);

IActorSystem is a Singleton. If ILoggerFactory is registered, a logger is automatically injected.

Custom IEventStore

public sealed class PostgresEventStore : IEventStore
{
    public ValueTask<ulong> AppendAsync(Guid actorId, ulong expectedVersion,
        IReadOnlyList<IDomainEvent> events) { /* INSERT with concurrency check */ }

    public ValueTask<IReadOnlyList<IDomainEvent>> LoadAsync(Guid actorId)
    { /* SELECT ordered by version */ }
}

Design Philosophy (克制 / 专注 / 优雅 / 高效)

Use Cases

• Agentic AI systems — each AI agent is an actor with conversation state
• Workflow orchestration — actors model long-running business processes
• Game server state — event-sourced actors for player/game state
• IoT device state — in-memory actors with periodic snapshotting

Packages

Comparison

License

MIT — see LICENSE.