Functorium.Testing 1.0.0-alpha.2

Functorium

English | 한국어

Functorium is named from functor + dominium with a touch of fun. dominium is Latin for "dominion, ownership" — Domain is not just a scope, but the problem space we own and govern.

Functorium is an AI Native .NET framework where AI agents directly guide domain design and generate code. The result compiles into production code with functional architecture + DDD + Observability built in.

• Learning is excitement.
• Learning is humility.
• Learning is altruism.

6 specialist AI agents guide a 7-step workflow from requirements analysis to testing. At each step, design documents and compilable C# code are generated simultaneously. No need to manually make hundreds of architecture decisions.

Functorium is designed for .NET teams practicing enterprise DDD, teams seeking to bridge the language gap between development and operations, and architects systematically adopting functional DDD architecture.

Problems to Solve

1. Domain logic is mixed with exceptions and implicit side effects — Business rule success and failure are handled via exceptions, making flow unpredictable and composition impossible.
2. Development language and operations language are separated — Feature specifications and operational requirements are managed in different systems, preventing a common language from being established and accumulating interpretation gaps.
3. Observability is added as an afterthought — Logs, metrics, and traces are attached separately after implementation is complete, causing critical context to be lost during incident analysis.

These are not simply process problems — they are problems of design philosophy and structure.

Mediator, LanguageExt, FluentValidation, and OpenTelemetry are each excellent. But integrating them into a coherent DDD architecture requires hundreds of decisions about error propagation, pipeline ordering, observability boundaries, and type constraints. Functorium makes these decisions once, consistently — and AI agents automatically apply these decisions to your project.

See the Change in 30 Seconds — From Text to Code

What you write — 3 lines of business rules:

• Email cannot be empty
• Email cannot exceed 320 characters
• Email must be in a valid format

What AI generates — A type-safe, composable functional validation pipeline without exceptions:

public sealed partial class Email : SimpleValueObject<string>
{
    public const int MaxLength = 320;

    private Email(string value) : base(value) { }

    public static Fin<Email> Create(string? value) =>
        CreateFromValidation(Validate(value), v => new Email(v));

    // Each validation condition failure auto-generates a corresponding error code:
    //   NotNull    → "DomainErrors.Email.Null"
    //   NotEmpty   → "DomainErrors.Email.Empty"
    //   MaxLength  → "DomainErrors.Email.TooLong"
    //   Matches    → "DomainErrors.Email.InvalidFormat"
    // Composite Value Objects use the Apply pattern to validate multiple fields
    // in parallel, collecting all errors at once.
    public static Validation<Error, string> Validate(string? value) =>
        ValidationRules<Email>
            .NotNull(value)
            .ThenNotEmpty()
            .ThenNormalize(v => v.Trim().ToLowerInvariant())
            .ThenMaxLength(MaxLength)
            .ThenMatches(EmailRegex(), "Invalid email format");

    // For ORM/Repository restoration — accepts only already-normalized data
    public static Email CreateFromValidated(string value) => new(value);

    public static implicit operator string(Email email) => email.Value;
}

Just define business rules in text. This complex but safe code is generated by AI agents.

<details> <summary><strong>Comparison with traditional C# exception handling</strong> — Why Fin<T> instead of exceptions?</summary>

Before — Traditional C# validation. Exceptions are landmines buried in control flow:

public class Email
{
    public Email(string value)
    {
        if (string.IsNullOrWhiteSpace(value))
            throw new ArgumentException("Email cannot be empty");   // Runtime bomb
                                                                    // if the next developer forgets try-catch, the system dies
        Value = value;
    }
    public string Value { get; }
}

After — Functorium's functional validation. Failure possibility is explicit in the return type — if you don't handle it, it won't compile:

public sealed partial class Email : SimpleValueObject<string>
{
    public static Fin<Email> Create(string? value) =>               // Fin<T>: success or structured error
        CreateFromValidation(Validate(value), v => new Email(v));   // Composable pipeline without exceptions
}

</details>

This is how AI generates exception-free, safe code structures automatically.

Humans Define Rules, AI Builds Plumbing, Observability Translates Back

"Can I debug AI-written monad code at 2 AM?"

The framework's automatic error classification + structured context logs + dashboards — built into every Command/Query — translate code state into human language.

How AI Breaks Through the Problems

From Problem to Code — Structure Connected by AI

7-Step Workflow

From PRD writing to testing, 7 skills + 6 specialist agents guide the way.

project-spec                    : PRD writing, Ubiquitous Language, Aggregate boundary extraction
  → architecture-design         : Project structure, layer composition, infrastructure decisions
  → domain-develop              : Value Object, Entity, Aggregate, Specification implementation
  → application-develop         : CQRS usecase, Port design and implementation
  → adapter-develop             : Repository, Query Adapter, Endpoint, DI registration
  → observability-develop       : KPI→metric mapping, dashboards, alerts, ctx.* propagation
  → test-develop                : Unit/integration/architecture rule test writing

domain-review                   : DDD review of existing code and improvement guidance (standalone skill)

Each step follows a 4-stage document pattern. Every design decision has traceable rationale:

00-business-requirements        : Business rule definition
  →  01-type-design-decisions   : Invariant → type mapping
  →  02-code-design             : C# pattern design
  →  03-implementation-results  : Compilable code + tests

6 Specialist Agents — Relay Timeline

Each agent takes the output of the previous stage, adds its own expertise, and passes the baton to the next:

Human: Business requirements text
  ↓
product-analyst         → Ubiquitous Language + Aggregate boundaries
  ↓
domain-architect        → Invariant classification + type mapping (VO, Entity, Aggregate)
  ↓
application-architect   → CQRS usecases + Port interfaces
  ↓
adapter-engineer        → Repository, Endpoint, DI, Observable Port
  ↓
observability-engineer  → KPI→metric mapping + dashboards + alerts
  ↓
test-engineer           → Unit/integration/architecture rule tests

AI-Generated Artifacts

• Value Objects (Always-valid, structured error codes)
• AggregateRoot (with domain events)
• CQRS Command/Query usecases
• EF Core Repository + Dapper Query Adapter
• FastEndpoints API endpoints
• Observable Port (automatic 3-Pillar instrumentation)
• Unit tests, integration tests, architecture rule tests
• Design documents for all stages (traceable design rationale)

AI-Generated Code: Functional Architecture in Detail

Building on the Email implementation above, let's explore additional framework patterns. For CQRS Command/Query usecase implementation examples, see the CQRS Repository Tutorial.

<details> <summary><strong>Domain Model in Detail</strong> — Value Object, Entity, AggregateRoot, DomainError, Domain Event</summary>

The domain-architect agent of the domain-develop skill classifies business invariants and maps them to the Functorium type system. All core business logic resides within the domain model, and entities, value objects, aggregates, and domain services have clear responsibilities.

Value Object — Ensures value-based equality and immutability:

public abstract class AbstractValueObject : IValueObject, IEquatable<AbstractValueObject>
{
    protected abstract IEnumerable<object> GetEqualityComponents();

    // Value-based equality, cached hash code, ORM proxy handling
}

Entity / AggregateRoot — Provides Ulid-based IDs and domain event management:

public interface IEntityId<T> : IEquatable<T>, IComparable<T>
    where T : struct, IEntityId<T>
{
    Ulid Value { get; }
    static abstract T New();
    static abstract T Create(Ulid id);
    static abstract T Create(string id);
}

public abstract class AggregateRoot<TId> : Entity<TId>, IDomainEventDrain
    where TId : struct, IEntityId<TId>
{
    protected void AddDomainEvent(IDomainEvent domainEvent);
    public void ClearDomainEvents();
}

DomainError — Ensures recoverability through structured error codes:

// Auto-generated error code: "DomainErrors.Email.Empty"
DomainError.For<Email>(new Empty(), value, "Email cannot be empty");

// Auto-generated error code: "DomainErrors.Password.TooShort"
DomainError.For<Password>(new TooShort(MinLength: 8), value, "Password too short");

Domain Event — Integrates Mediator-based Pub/Sub with event tracking:

public interface IDomainEvent : INotification
{
    DateTimeOffset OccurredAt { get; }
    Ulid EventId { get; }
    string? CorrelationId { get; }
    string? CausationId { get; }
}

</details>

<details> <summary><strong>CQRS and Functional Composition in Detail</strong> — Repository, Query Port, Command/Query Interfaces</summary>

The application-develop skill assembles domain models into CQRS usecases. Core domain logic is composed of pure functions. By maintaining a structure where identical inputs always produce identical outputs, the logic becomes predictable and easy to test. Side effects (database, external APIs, messaging, file I/O) are handled outside the domain logic. The IO monad provides built-in advanced features such as Timeout, Retry (exponential backoff), Fork (parallel execution), and Bracket (resource lifecycle management), enabling type-safe fault tolerance configuration for external service calls.

Fin<T>, FinT<IO, T> — Handles errors with explicit result types instead of exceptions. The Command path Repository returns FinT<IO, T> to explicitly express side effects:

// Command: IRepository — Per-Aggregate Root CRUD, change tracking and transaction management via EF Core
public interface IRepository<TAggregate, TId> : IObservablePort
    where TAggregate : AggregateRoot<TId>
    where TId : struct, IEntityId<TId>
{
    FinT<IO, TAggregate> Create(TAggregate aggregate);
    FinT<IO, TAggregate> GetById(TId id);
    FinT<IO, TAggregate> Update(TAggregate aggregate);
    FinT<IO, int> Delete(TId id);

    // Bulk operations
    FinT<IO, Seq<TAggregate>> CreateRange(IReadOnlyList<TAggregate> aggregates);
    FinT<IO, Seq<TAggregate>> GetByIds(IReadOnlyList<TId> ids);
    FinT<IO, Seq<TAggregate>> UpdateRange(IReadOnlyList<TAggregate> aggregates);
    FinT<IO, int> DeleteRange(IReadOnlyList<TId> ids);
}

CQRS — Structurally separates write and read paths, applying optimized data access strategies for each. Command uses IRepository + EF Core for Aggregate consistency and transactions, while Query uses IQueryPort + Dapper for direct DTO projection without Aggregate reconstruction. Both paths unify results through FinResponse<T>:

// Command
public interface ICommandRequest<TSuccess> : ICommand<FinResponse<TSuccess>> { }
public interface ICommandUsecase<in TCommand, TSuccess>
    : ICommandHandler<TCommand, FinResponse<TSuccess>>
    where TCommand : ICommandRequest<TSuccess> { }

// Query
public interface IQueryRequest<TSuccess> : IQuery<FinResponse<TSuccess>> { }
public interface IQueryUsecase<in TQuery, TSuccess>
    : IQueryHandler<TQuery, FinResponse<TSuccess>>
    where TQuery : IQueryRequest<TSuccess> { }

// Query: IQueryPort — Direct DTO projection without Aggregate reconstruction, lightweight SQL mapping via Dapper
public interface IQueryPort<TEntity, TDto> : IQueryPort
{
    FinT<IO, PagedResult<TDto>> Search(
        Specification<TEntity> spec, PageRequest page, SortExpression sort);

    FinT<IO, CursorPagedResult<TDto>> SearchByCursor(
        Specification<TEntity> spec, CursorPageRequest cursor, SortExpression sort);

    IAsyncEnumerable<TDto> Stream(
        Specification<TEntity> spec, SortExpression sort,
        CancellationToken cancellationToken = default);
}

</details>

<details> <summary><strong>Observability by Design in Detail</strong> — Pipeline, Observable Port, ctx.*, Error Classification</summary>

The observability-develop skill embeds operational stability from the design phase. All Commands and Queries automatically pass through a pipeline with built-in Observability (Logging, Metrics, Tracing) and validation. Developers do not need to write log code manually.

flowchart TD
    A["Common: Observability + Validation
    (Logging · Metrics · Tracing · Validation)"] --> B[Command Path]
    A --> C[Query Path]
    B --> D["Transaction + Domain Event Publishing"]
    C --> E["Caching + Pagination"]

Command publishes domain events within transaction boundaries, and Query provides caching and pagination. For the exact pipeline stages and order, see the Observability Specification.

IObservablePort — All external dependencies are abstracted as observable ports:

public interface IObservablePort
{
    string RequestCategory { get; }
}

ctx. 3-Pillar Enrichment* — The Source Generator automatically transforms Request/Response/DomainEvent properties into ctx.{snake_case} fields, propagating business context simultaneously to Logging, Tracing, and Metrics. Metrics tags can be opted in with [CtxTarget(CtxPillar.All)].

[GenerateObservablePort] — The Source Generator automatically creates Observable wrappers for Adapters, transparently providing OpenTelemetry-based Tracing, Logging, and Metrics:

[GenerateObservablePort]  // → Observable{ClassName} auto-generated (e.g., ObservableOrderRepository)
public class OrderRepository : IRepository<Order, OrderId> { ... }

Automatic Error Classification — Business rule violations (e.g., "insufficient stock") are classified as expected, system failures (NullReferenceException) as exceptional, and compound validation failures as aggregate. The error.type field allows separate querying of business errors and system failures in Seq/Grafana.

</details>

Getting Started

Installation

# Load both plugins simultaneously
claude --plugin-dir ./.claude/plugins/functorium-develop --plugin-dir ./.claude/plugins/release-note

Getting Started with AI (Recommended)

Start with "Write a PRD for an e-commerce platform" and the AI agents will guide you through the 7-step workflow.

Getting Started with Packages

# Core domain modeling — Value Object, Entity, AggregateRoot, Specification, error system
dotnet add package Functorium

# Infrastructure adapters — OpenTelemetry, Serilog, EF Core, Dapper, Pipeline
dotnet add package Functorium.Adapters

# Code generation — [GenerateObservablePort], [GenerateEntityId], CtxEnricher
dotnet add package Functorium.SourceGenerators

# Test utilities — ArchUnitNET, xUnit extensions, integration test fixtures
dotnet add package Functorium.Testing

5-Minute Quickstart: Build a Value Object → AggregateRoot → Command Usecase in 5 minutes at Quickstart.

First Tutorial: Dive deep into Value Objects at the Functional ValueObject Tutorial.

Full Documentation: https://hhko.github.io/Functorium

release-note (v1.0.0) — Release Note Automation

C# script-based data collection, Conventional Commits analysis, Breaking Changes detection, release note writing, and validation — a 5-step workflow automated by 1 skill + 1 agent.

Detailed documentation: AX (AI Transformation)

Architecture Overview

The system is composed of three layers. The domain depends on nothing external, and dependencies always flow inward.

• Domain Layer — Pure business logic. Entity, AggregateRoot, Value Object, Specification, DomainError, Domain Event, Repository port (IRepository), IObservablePort. Expresses business rules through pure functions without external dependencies.
• Application Layer — Usecase orchestration. CQRS (ICommandRequest, IQueryRequest), FinResponse, IQueryPort (read-only DTO projection), FluentValidation extensions, FinT LINQ composition, Domain Event publishing, IUnitOfWork. Connects domain logic with infrastructure and manages side effect boundaries.
• Adapter Layer — Infrastructure implementation. OpenTelemetry configuration, Usecase Pipeline (Observability + Validation built-in, including CtxEnricher), Observable domain event publishing, structured loggers, DapperQueryAdapterBase, AdapterError, 5 Source Generators ([GenerateObservablePort], [GenerateEntityId], CtxEnricher, DomainEventCtxEnricher, [UnionType]). Depends on domain, but domain does not depend on infrastructure.

Observability

Functorium provides unified observability (Logging, Metrics, Tracing) based on OpenTelemetry.

Three Observation Paths

The Application layer (EventId 1001–1004) and Adapter layer (EventId 2001–2004) use identical request.* / response.* / error.* naming, enabling end-to-end request flow tracking with a single dashboard query.

For detailed specifications and guides, see the documentation site:

• Observability Specification — Field/Tag structure, ctx.* 3-Pillar Enrichment, Meter/Instrument specification
• Logging Guide — Structured logging detailed guide
• Metrics Guide — Metrics collection and analysis guide
• Tracing Guide — Distributed tracing detailed guide

Quality Strategy — Half of Generation is Verification

Why AI-generated code can be deployed to production — a triple verification gate blocks architecture violations, business rule errors, and observability gaps at build time.

Gate 1: Architecture Rule Tests — Structural Integrity

If the domain layer depends on infrastructure? The build fails:

[Fact]
public void DomainLayer_ShouldNotDependOn_ApplicationLayer()
{
    Types()
        .That().ResideInNamespace(DomainNamespace)
        .Should().NotDependOnAnyTypesThat()
        .ResideInNamespace(ApplicationNamespace)
        .Check(Architecture);
}

Functorium.Testing provides 6 TestSuite base classes — just inherit and 21+ architecture rules are automatically applied:

Gate 2: Domain Model Unit Tests — Business Rule Verification

The test-engineer agent automatically generates boundary condition tests for all Value Objects:

[Theory]
[InlineData("")]
[InlineData(null)]
public void Create_ShouldFail_WhenValueIsEmptyOrNull(string? value)
{
    var actual = Email.Create(value);
    actual.IsFail.ShouldBeTrue();
}

[Fact]
public void Create_ShouldFail_WhenValueExceedsMaxLength()
{
    var value = new string('a', Email.MaxLength + 1);
    var actual = Email.Create(value);
    actual.IsFail.ShouldBeTrue();
}

Gate 3: Build Failure Scenarios — Violations are Blocked Immediately

When AI-generated code violates rules, the build pipeline blocks immediately:

FAILED  ValueObject_ShouldBe_PublicSealedWithPrivateConstructors
  ArchitectureRuleViolation:
    Class 'Email' violates ValueObject Visibility Rule
    — Expected: public sealed with all private constructors
    — Actual: constructor 'Email(string)' is public

  1 architecture rule violation(s) detected.

Generation is half the system; ruthless verification is the other half. Architecture rule tests verify AI-generated code and human-written code equally.

Documentation

Full Documentation Site: https://hhko.github.io/Functorium

Tutorials

Samples

Packages

Tech Stack