accordant-state

Designing State in Accordant

State is what an external observer needs to know to predict what an operation should return. Keep it minimal — only track what's necessary to define correct behavior.

The [State] Attribute

Use [State] on a partial class to get automatic cloning, equality, and hashing:

[State]
public partial class BankState
{
    public Dictionary<string, decimal> Accounts { get; set; } = new();
}

The source generator handles:

• Deep cloning for immutable state transitions
• Equality comparison for state deduplication
• Hashing for state graph exploration

State Design Principles

Keep It Minimal

Ask: "Does any operation need this to determine its response?" If no, leave it out.

// ❌ Too detailed - includes implementation concerns
[State]
public partial class BadState
{
    public Dictionary<string, AccountEntity> Accounts { get; set; }  // EF entities
    public DateTime LastModified { get; set; }  // Not needed for behavior
    public string ConnectionString { get; set; }  // Implementation detail
}

// ✅ Just what operations need
[State]
public partial class GoodState
{
    public Dictionary<string, decimal> Accounts { get; set; } = new();  // Just balances
}

Nested State Classes

For complex domains, nest state classes:

[State]
public partial class AppState
{
    public Dictionary<string, UserState> Users { get; set; } = new();
}

[State]
public partial class UserState
{
    public string Name { get; set; } = string.Empty;
    public Dictionary<string, TodoState> Todos { get; set; } = new();
}

[State]
public partial class TodoState
{
    public string Title { get; set; } = string.Empty;
    public bool Completed { get; set; } = false;
}

State Transitions

Operations return expected outcomes that describe both the response and the next state.

No State Change: .SameState()

For errors or read-only operations:

// Error - doesn't modify state
if (!state.Accounts.ContainsKey(accountId))
    return Expect.That<ApiResult<decimal>>(r => r.IsNotFound).SameState();

// Read-only operation
return Expect.That<ApiResult<decimal>>(r => r.IsSuccess && r.Data == balance).SameState();