tw-aggregate-pattern

name	tw-aggregate-pattern
description	**TIMEWARP SKILL** — the golden aggregate-root pattern: typed id, `Entity<TId>` base, fail-closed `Create`, named mutations with no public setters, a private nested `Invariants` validator, and save-time enforcement via `DomainInvariantsGuard`/`AggregateDbContext`. Invoke before adding or reviewing an `IAggregateRoot`, or when TWA0011/TWA0012 fire. WHEN: add an aggregate, IAggregateRoot, aggregate root, TWA0011, TWA0012, Invariants validator, typed id.
when-to-use	aggregate root, IAggregateRoot, Entity<TId>, typed id, TypedId, Invariants validator, DomainInvariantsGuard, AggregateDbContext, TWA0011, TWA0012, fail-closed construction, named mutation, concurrency token, Version

Aggregate pattern (TWA0011/0012)

An aggregate is a domain entity that is the consistency boundary for a set of invariants. Every aggregate root in this repository follows the same golden pattern. This skill is the pattern SSOT; how-to-add-your-aggregate.md is the human end-to-end walkthrough that defers to it.

Detection — when to invoke

Signal	How to find it
Adding a new IAggregateRoot	any domain type that owns its own consistency boundary
TWA0011 / TWA0012 diagnostic	analyzer output names the aggregate type
"Where does the invariants check run?"	save path, not construction
Reviewing a Create/mutation method for a domain type	fail-closed construction check

The golden pattern

• Typed id. The aggregate's id is a [TypedId] readonly partial record struct (e.g. ProfileId), never a raw Guid. See web/features/profile/profile-id-domain.cs.
• Entity<TId> base. The aggregate inherits TimeWarp.Foundation.Entities.Entity<TId> (get-only typed Id, identity-based equality, a store-owned Version concurrency token) and implements the marker interface IAggregateRoot.
• Fail-closed construction. A private constructor plus a static Create(...) factory with guard clauses — an aggregate can never exist half-initialized or with an obviously-invalid required field.
• Named mutations, no public setters. State changes are intention-revealing methods (Rename, SetLanguage, ...), never { get; set; }.
• Nested Invariants validator. A private sealed class Invariants : AbstractValidator<T> declares the aggregate's full rule set. It stays private so contract-validator auto-registration (AddValidatorsFromAssemblyContaining) never picks it up as a request validator.
• Save-time enforcement. DomainInvariantsGuard discovers and runs the nested Invariants validator for every changed IAggregateRoot from AggregateDbContext.SaveChanges(Async) before the save proceeds. Host contexts (e.g. PostgresDbContext) inherit that base; they do not reimplement the hook. Guard clauses in Create/mutations and the save-time validator are complementary, not redundant: the former makes invalid states hard to construct, the latter makes them impossible to persist regardless of which code path produced them. Child-only mutations resolve to the owning root so invariants and Version still run.

Placement

An aggregate's domain type is <name>-domain.cs in its owning slice, and its typed id is <name>-id-domain.cs alongside it — both follow the <name>[-<function>]-<layer>.cs filename grammar for the domain layer. See tw-feature-placement for the full grammar, registry, and use-case-folder rules; this skill covers the aggregate's internal shape, not where the file lives.

Enforcement map

Rule	Requires	Why
TWA0011	An IAggregateRoot must declare a nested Invariants : AbstractValidator<T>	Fail-closed: no validator means DomainInvariantsGuard cannot check the aggregate at save time
TWA0012	That nested Invariants must be private	Keeps it out of AddValidatorsFromAssemblyContaining auto-registration — it is a save-time domain check, not a request validator

Exemplar

web/features/profile/profile-domain.cs + profile-id-domain.cs — read both before adding a new aggregate. Its EF mapping (profile-entity-type-configuration-infrastructure.cs — table/schema profiles, TypedId key conversion) is applied by PostgresDbContext via ApplyConfigurationsFromAssembly. Version's .IsConcurrencyToken() is supplied for free by the AggregateDbContext Version convention — an aggregate's own mapping does not declare it.

Related skills and pointers

• tw-feature-placement — filename grammar and layer membership (<name>[-<function>]-<layer>.cs, the domain layer, registry)
• tw-slice-isolation — which slice an aggregate belongs to before placement
• how-to-add-your-aggregate.md — human end-to-end walkthrough (domain → EF mapping → host registration → application use → tests)