Optima.Net.Domain 1.0.0

Optima.Net.Domain

Optima.Net.Domain is a lightweight, framework-agnostic toolkit that provides explicit building blocks for writing clear, maintainable, and auditable Domain-Driven Design (DDD) code.

This library is intentionally focused. It does not try to be a framework. Instead, it provides a small set of primitives that help you express facts, decisions, and outcomes in a way that scales from simple business rules to finance-grade decision systems.

This document is both:

• a comprehensive reference, and
• a step-by-step tutorial for engineers new to DDD-style modelling.

If you read it top-to-bottom, you should be able to confidently apply Specifications and Policies in real systems.

If you like what I did here or it inspired you to learn something new, please consider buying me a coffee: https://buymeacoffee.com/snamretsuek The support would be greatly appreciated!

Table of Contents

1. Motivation and Mental Model
2. Core Concepts Overview
3. Specifications (Sync)
4. Composite Specifications
5. Policies (Sync)
6. Composite Policies
7. Async Specifications and Policies
8. Diagnostics
9. Diagnostic Helpers
10. Decisions / Outcomes
11. Identity and Naming
12. End-to-End Examples
13. Design Philosophy and Boundaries

1. Motivation and Mental Model

In many systems, business rules end up:

• buried in if statements,
• duplicated across services,
• tightly coupled to infrastructure,
• or impossible to explain after the fact.

Optima.Net.Domain exists to fix this by making rules and decisions explicit.

The Mental Model

This separation is the foundation of the library.

2. Core Concepts Overview

Specifications

• Express facts
• Are small and composable
• Contain no side effects
• Can be reused across policies

Policies

• Express business intent
• Are fulfilled only if all required facts hold
• Often composed from multiple specifications
• Can be composed from other policies

Diagnostics

• Observe evaluation
• Never change behaviour
• Produce immutable result trees

Decisions

• Capture evaluation outcomes
• Are immutable and serializable
• Suitable for logging and auditing

3. Specifications (Sync)

A specification answers a single factual question.

Example Domain: Orders

public sealed class OrderLine
{
    public string Product { get; }
    public decimal Price { get; }
    public bool CanShipByAir { get; }

    public OrderLine(string product, decimal price, bool canShipByAir)
    {
        Product = product;
        Price = price;
        CanShipByAir = canShipByAir;
    }
}

public sealed class Order
{
    private readonly List<OrderLine> _lines = new();

    public IReadOnlyCollection<OrderLine> Lines => _lines;
    public decimal Total => _lines.Sum(l => l.Price);

    public void AddLine(OrderLine line) => _lines.Add(line);
}

Individual Specifications

public sealed class OrderHasLinesSpec : Specification<Order>
{
    public override bool IsSatisfiedBy(Order order)
        => order.Lines.Any();
}

public sealed class OrderCanShipByAirSpec : Specification<Order>
{
    public override bool IsSatisfiedBy(Order order)
        => order.Lines.All(l => l.CanShipByAir);
}

public sealed class OrderTotalExceedsSpec : Specification<Order>
{
    private readonly decimal _threshold;

    public OrderTotalExceedsSpec(decimal threshold)
        => _threshold = threshold;

    public override bool IsSatisfiedBy(Order order)
        => order.Total > _threshold;
}

Each specification:

• Answers one question
• Has no knowledge of business intent
• Is independently testable

4. Composite Specifications

Specifications can be composed to express more complex facts.

var shippableOrderSpec =
    new OrderHasLinesSpec()
        .And(new OrderCanShipByAirSpec());

var discountEligibleSpec =
    new OrderHasLinesSpec()
        .And(new OrderTotalExceedsSpec(500m));

Composite specifications still express facts. They do not represent decisions.

5. Policies (Sync)

Policies express decisions and are typically built from specifications.

Order Fulfillment Policy

public sealed class OrderFulfillmentPolicy : Policy<Order>
{
    private static readonly ISpecification<Order> _specification =
        new OrderHasLinesSpec()
            .And(new OrderCanShipByAirSpec());

    public override bool IsSatisfiedBy(Order order)
        => _specification.IsSatisfiedBy(order);
}

This policy answers:

May this order be fulfilled?

Discount Eligibility Policy

public sealed class OrderDiscountPolicy : Policy<Order>
{
    private static readonly ISpecification<Order> _specification =
        new OrderHasLinesSpec()
            .And(new OrderTotalExceedsSpec(500m));

    public override bool IsSatisfiedBy(Order order)
        => _specification.IsSatisfiedBy(order);
}

6. Composite Policies

In many domains, multiple policies must be fulfilled before progression is allowed.

Finance Example: Credit Application

public sealed class CreditApplication
{
    public decimal Amount { get; }
    public bool HasPriorDefaults { get; }
    public bool PassedAmlChecks { get; }

    public CreditApplication(
        decimal amount,
        bool hasPriorDefaults,
        bool passedAmlChecks)
    {
        Amount = amount;
        HasPriorDefaults = hasPriorDefaults;
        PassedAmlChecks = passedAmlChecks;
    }
}

Specifications

public sealed class CreditWithinLimitSpec : Specification<CreditApplication>
{
    public override bool IsSatisfiedBy(CreditApplication app)
        => app.Amount <= 100_000m;
}

public sealed class NoPriorDefaultsSpec : Specification<CreditApplication>
{
    public override bool IsSatisfiedBy(CreditApplication app)
        => !app.HasPriorDefaults;
}

public sealed class PassedAmlChecksSpec : Specification<CreditApplication>
{
    public override bool IsSatisfiedBy(CreditApplication app)
        => app.PassedAmlChecks;
}

Policies Built from Specifications

public sealed class CreditApprovalPolicy : Policy<CreditApplication>
{
    private static readonly ISpecification<CreditApplication> _specification =
        new CreditWithinLimitSpec()
            .And(new NoPriorDefaultsSpec());

    public override bool IsSatisfiedBy(CreditApplication app)
        => _specification.IsSatisfiedBy(app);
}

public sealed class AmlClearancePolicy : Policy<CreditApplication>
{
    private static readonly ISpecification<CreditApplication> _specification =
        new PassedAmlChecksSpec();

    public override bool IsSatisfiedBy(CreditApplication app)
        => _specification.IsSatisfiedBy(app);
}

Composite Policy Gate

public sealed class CreditIssuancePolicy
    : CompositePolicy<CreditApplication>
{
    protected override IReadOnlyCollection<IPolicy<CreditApplication>> Policies =>
        new IPolicy<CreditApplication>[]
        {
            new CreditApprovalPolicy(),
            new AmlClearancePolicy()
        };
}

This expresses a progression gate:

Credit may only be issued if all required policies are fulfilled.

7. Async Specifications and Policies

Async variants exist for:

• Database checks
• External services
• Fraud / AML systems

public sealed class AsyncAmlSpec : AsyncSpecification<CreditApplication>
{
    public override Task<bool> IsSatisfiedByAsync(
        CreditApplication app,
        CancellationToken ct = default)
        => Task.FromResult(app.PassedAmlChecks);
}

Async policies mirror sync policies exactly. Sync and async are never mixed.

8. Diagnostics

Diagnostics explain why something passed or failed.

Specification Diagnostics

var evaluator = new DiagnosticSpecificationEvaluator();
var diagnostics = evaluator.Evaluate(specification, order);

Policy Diagnostics

var evaluator = new PolicyDiagnosticEvaluator();
var diagnostics = evaluator.Evaluate(policy, application);

Diagnostics produce immutable trees describing evaluation.

9. Diagnostic Helpers

Helpers make diagnostics usable without changing behaviour.

var failedSpecs = diagnostics.FailedSpecificationTypes();
var failedPolicies = diagnostics.FailedPolicyTypes();

var leafFailures = diagnostics.FailedLeaves();

10. Decisions / Outcomes

Decisions capture evaluation outcomes.

var decision = policy.Decide(application);

public sealed record PolicyDecision(
    string PolicyType,
    bool Fulfilled);

Decisions are:

• Immutable
• Serializable
• Suitable for audit trails

11. Identity and Naming

Diagnostics use structural identity by default:

PolicyType = policy.GetType().Name

Optional interfaces allow human-readable naming without affecting diagnostics.

12. End-to-End Example

if (!creditIssuancePolicy.IsSatisfiedBy(application))
{
    var diagnostics =
        policyDiagnosticEvaluator.Evaluate(
            creditIssuancePolicy,
            application);

    var failedPolicies = diagnostics.FailedPolicyTypes();
}

This flow is:

• Explicit
• Deterministic
• Auditable
• Framework-free

13. Design Philosophy and Boundaries

Optima.Net.Domain intentionally avoids:

• Rule engines
• Workflow engines
• Infrastructure concerns
• Base entities or repositories

Its purpose is singular:

Make domain intent explicit and executable.

If a rule matters, model it as a specification.
If a decision matters, model it as a policy.

© Optima.Net.Domain