Statesman 0.3.0

Statesman

Statesman is a declaration-driven state runtime and append-only state ledger for .NET.

It gives large, loosely coupled systems a practical route to authoritative state without requiring a Flux or Redux rewrite. A Statesman composition root declares what state exists, where it comes from, how it may change, how fresh it must be, how long its history is retained, where that history is stored, and how the state is observed.

The declaration is executable architecture. At build time it becomes an immutable, deterministic manifest. At runtime it coordinates typed reads, reactive writes, proactive loading, reducers, freshness, optimistic concurrency, history, observation, and storage.

StateKey<UserServiceState> user =
    StateKey.Define<UserServiceState>("users/user");

StatesmanDeclaration declaration = Statesman.Declare("back-office", "1.0")
    .Defaults(defaults => defaults
        .Freshness(freshness => freshness
            .FreshFor(TimeSpan.FromMinutes(5))
            .ServeStaleFor(TimeSpan.FromMinutes(30))
            .StaleWhileRevalidate())
        .Retain(history => history
            .Last(250)
            .For(TimeSpan.FromDays(30))))
    .Container("users", users => users
        .Isolated()
        .State(user, state => state
            .Partitioned()
            .Initial(new UserServiceState("", [], false))
            .Load(load => load
                .From<IUserApi, UserProfile>("profile",
                    (api, context, ct) =>
                        api.GetProfileAsync(context.Address.Partition.Value, ct))
                .Into((current, profile, _) => current with
                {
                    DisplayName = profile.DisplayName,
                })
                .From<IUserApi, IReadOnlyList<string>>("permissions",
                    (api, context, ct) =>
                        api.GetPermissionsAsync(context.Address.Partition.Value, ct))
                .Into((current, permissions, _) => current with
                {
                    Permissions = permissions,
                })
                .InParallel()
                .RequireAll())
            .Refresh(refresh => refresh
                .OnFirstRead()
                .WhenStale()
                .Every(TimeSpan.FromMinutes(10))
                .OnSignal("user.changed"))
            .Interact<SetEnabled>("set-enabled", interaction => interaction
                .Require((_, command) => command.ActorCanAdmin,
                    "The actor cannot administer users.")
                .Reduce((current, command) => current with
                {
                    Enabled = command.Enabled,
                }))))
    .Build();

builder.Services.AddStatesman(declaration, statesman => statesman
    .UseFileSystemStore("local", "./state")
    .UseRedisStore("shared", connection));
builder.Services.AddStatesmanHosting();

IState<UserServiceState> ada = statesman.State(user, "user-42");
IStateSnapshot<UserServiceState> snapshot =
    await ada.GetAsync(StateReadOptions.Fresh);

await ada.DispatchAsync(new SetEnabled(
    Enabled: true,
    ActorCanAdmin: true));

await statesman.SignalAsync(new StateSignal(
    "user.changed",
    Partition: "user-42"));

What Statesman is

Statesman is a higher-order state abstraction. It sits above storage, transport, polling, event delivery, caches, and domain services. It does not ask those systems to become Statesman-aware. They remain sources and sinks. Statesman owns the authoritative runtime view and records how that view changed.

A state has more than a value. It has a typed identity, partition, revision, global ledger position, status, freshness window, schema version, source, causation, metadata, error information, retention policy, and declared interaction surface.

What Statesman is not

Statesman is not a database, distributed transaction coordinator, message broker, event-sourcing framework, entity tracker, or UI framework. A ledger provider may use a database or Redis, but Statesman does not expose their query models as its programming model. It deliberately keeps domain-facing code independent from the persistence mechanism.

Core model

Package map

The core packages target .NET 8, 9, and 10. The EF Core provider and samples target .NET 10.

First run

dotnet restore Statesman.slnx
dotnet build Statesman.slnx --configuration Release --no-restore
dotnet test Statesman.slnx --configuration Release --no-build
dotnet run --project samples/Statesman.Sample.Console

The repository pins the .NET 10.0.303 SDK. See Getting started for the smallest useful declaration, Architecture for the complete model, and the published DocFX site for browsable guides and API reference.

Current implementation scope

This repository is an implementation-ready first release, not a mock scaffold. It includes the public contracts, fluent declaration system, runtime, in-memory and external providers, analyzers, host integrations, examples, tests, CI, packaging, CodeQL, Codecov coverage reporting, a DocFX site, and design documentation.

Run eng/build.ps1 or eng/build.sh for the local release validation loop, or let the included GitHub Actions workflows perform restore, build, tests, coverage, package creation, docs publishing, and optional NuGet publishing.

Design principles

1. One declared authority, many migration paths. Existing code can begin by pushing updates into Statesman. Loaders, reducers, immutable state values, and analyzers can follow incrementally.
2. The declaration is inspectable. Runtime behavior must be visible in a stable manifest instead of hidden across registration callbacks and conventions.
3. History is a first-class consequence of state. Every authoritative change has a revision and lineage, even when retention later prunes it.
4. Storage is replaceable. Domain code talks to state, never Redis keys, files, EF entities, or cache entries.
5. Reads state their consistency intent. Cached, current, refresh-if-stale, and fresh reads are explicit.
6. Concurrency is never last-write-wins by accident. Writes use expected revisions and retry pure updates or reducers against the newest snapshot.
7. Failure is state. Loader failures are observable ledger records and can retain a last-known value according to policy.
8. Boundaries say what they guarantee. A separate root is the hard identity and lifecycle boundary. Separate provider infrastructure makes it a storage failure boundary. Containers remain scopes within a root.

Documentation

• Getting started
• The declaration DSL
• State lifecycle and reads
• Containers, roots, and partitions
• Loaders and fan-in composition
• Interactions and reactive writes
• Migration guide
• Ledger and retention
• Storage providers
• ASP.NET Core and hosting
• Analyzers
• Testing — inline seeds, portable snapshot fixtures, ASP.NET Core, Playwright, and distributed E2E orchestration
• Observation and subscriptions
• Multiple roots
• Consistency and concurrency
• Public API map
• Diagnostics
• Production readiness
• Repository release readiness
• Architecture and invariants
• Implementation plan
• Roadmap

License

MIT. See LICENSE.