feat(phase-02a): packet 2 — shared kernel core

backend/Directory.Packages.props

@@ -19,6 +19,12 @@
     <PackageVersion Include="MediatR" Version="12.4.1" />
     <PackageVersion Include="FluentValidation" Version="11.10.0" />
 
+    <!-- Strongly-typed ID + value object source generator (ADR-0023).
+         Referenced via PrivateAssets="all" in every project that hosts
+         [ValueObject<>] declarations (SharedKernel for cross-cutting VOs,
+         each Modules.<X>.Domain for aggregate-root IDs). -->
+    <PackageVersion Include="Vogen" Version="7.0.0" />
+
     <!-- Test stack -->
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />
     <PackageVersion Include="xunit" Version="2.9.2" />

backend/src/LearnStack.SharedKernel/Domain/AuditableEntity.cs

@@ -0,0 +1,127 @@
+using LearnStack.SharedKernel.Identifiers;
+using LearnStack.SharedKernel.Persistence;
+using LearnStack.SharedKernel.Time;
+
+namespace LearnStack.SharedKernel.Domain;
+
+/// <summary>
+/// Mutable aggregate base. Carries the audit columns every tenant-owned
+/// table mirrors (<c>CreatedAt</c> / <c>CreatedBy</c> / <c>UpdatedAt</c> /
+/// <c>UpdatedBy</c> / <c>DeletedAt</c> / <c>DeletedBy</c> / <c>Version</c>)
+/// and implements <see cref="ISoftDelete"/> + <see cref="IOptimisticConcurrency"/>
+/// so the EF global-query-filter and concurrency-token wiring picks them up
+/// uniformly. Audit columns are populated by <see cref="MarkCreated"/> /
+/// <see cref="MarkUpdated"/> / <see cref="SoftDelete"/>, which command
+/// handlers call via the <see cref="IClock"/> they already inject.
+/// </summary>
+public abstract class AuditableEntity<TId>
+    : Entity<TId>, ISoftDelete, IOptimisticConcurrency
+    where TId : struct, IStronglyTypedId<Guid>
+{
+    protected AuditableEntity(TId id)
+        : base(id)
+    {
+    }
+
+    // EF Core / ORM materialization ctor.
+    protected AuditableEntity()
+    {
+    }
+
+    public DateTimeOffset CreatedAt { get; protected set; }
+
+    public UserId CreatedBy { get; protected set; }
+
+    public DateTimeOffset? UpdatedAt { get; protected set; }
+
+    public UserId? UpdatedBy { get; protected set; }
+
+    public DateTimeOffset? DeletedAt { get; protected set; }
+
+    public UserId? DeletedBy { get; protected set; }
+
+    public uint Version { get; protected set; }
+
+    /// <summary>
+    /// Convenience projection of <see cref="DeletedAt"/> for in-process
+    /// callers (aggregate methods, application services, mappers). EF
+    /// global query filters should gate on <see cref="DeletedAt"/> directly
+    /// (<c>e =&gt; e.DeletedAt == null</c>) — <see cref="IsDeleted"/> is a
+    /// computed CLR property and is NOT guaranteed to translate to SQL by
+    /// EF Core's expression translator. Packet 7 wires the filters
+    /// accordingly.
+    /// </summary>
+    public bool IsDeleted => DeletedAt.HasValue;
+
+    /// <summary>
+    /// Stamps <see cref="CreatedAt"/> / <see cref="CreatedBy"/> on first
+    /// persist. Throws when the aggregate already has a non-default
+    /// <see cref="CreatedAt"/> — audit-trail integrity rules out silent
+    /// overwrites.
+    /// </summary>
+    public void MarkCreated(DateTimeOffset at, UserId by)
+    {
+        EnsureValidAuditInput(at, by);
+
+        if (CreatedAt != default)
+        {
+            throw new InvalidOperationException(
+                "MarkCreated has already been called on this aggregate; the created-at / created-by columns are immutable after first stamp.");
+        }
+
+        CreatedAt = at;
+        CreatedBy = by;
+    }
+
+    /// <summary>
+    /// Stamps <see cref="UpdatedAt"/> / <see cref="UpdatedBy"/>. Called by
+    /// aggregate methods that mutate state; the audit pipeline reads these
+    /// values when writing the audit entry.
+    /// </summary>
+    public void MarkUpdated(DateTimeOffset at, UserId by)
+    {
+        EnsureValidAuditInput(at, by);
+
+        UpdatedAt = at;
+        UpdatedBy = by;
+    }
+
+    /// <summary>
+    /// Marks the entity as soft-deleted. Also bumps
+    /// <see cref="UpdatedAt"/> / <see cref="UpdatedBy"/> so the
+    /// "last touched at" timestamp is monotonic — replication / sync /
+    /// reporting jobs that scan on <c>UpdatedAt</c> see soft-deletes
+    /// without keying off <c>DeletedAt</c> separately. The audit row still
+    /// classifies the action as a delete via its own operation type.
+    /// </summary>
+    public void SoftDelete(DateTimeOffset at, UserId by)
+    {
+        EnsureValidAuditInput(at, by);
+
+        DeletedAt = at;
+        DeletedBy = by;
+        UpdatedAt = at;
+        UpdatedBy = by;
+    }
+
+    // Audit metadata must always be meaningful: the default timestamp
+    // (0001-01-01) and the default UserId (Guid.Empty) are programmer-error
+    // sentinels rather than legitimate audit values. Fail loud at the call
+    // site rather than persisting them.
+    private static void EnsureValidAuditInput(DateTimeOffset at, UserId by)
+    {
+        if (at == default)
+        {
+            throw new ArgumentException(
+                "Audit timestamp must be a meaningful instant, not default(DateTimeOffset). Pass the value from IClock.UtcNow.",
+                nameof(at));
+        }
+
+        if (by.Value == Guid.Empty)
+        {
+            throw new ArgumentException(
+                "Audit actor must be a real UserId, not default(UserId). Pass the resolved ITenantContext.UserId.",
+                nameof(by));
+        }
+    }
+}

backend/src/LearnStack.SharedKernel/Domain/DomainEvent.cs

@@ -0,0 +1,31 @@
+namespace LearnStack.SharedKernel.Domain;
+
+/// <summary>
+/// Base record for in-process domain events. Concrete events derive from
+/// this and add their own payload fields:
+/// <code>
+/// public sealed record CourseEnrolled(CourseId CourseId, UserId UserId) : DomainEvent;
+///
+/// // raised from inside an aggregate method:
+/// RaiseDomainEvent(new CourseEnrolled(Id, learnerId)
+/// {
+///     EventId = guids.NewUuidV7(),
+///     OccurredAt = clock.UtcNow,
+/// });
+/// </code>
+/// </summary>
+/// <remarks>
+/// <see cref="EventId"/> and <see cref="OccurredAt"/> are <c>required init</c>:
+/// every event MUST be stamped with the aggregate's injected
+/// <c>IGuidFactory</c> / <c>IClock</c>. Defaulting these to
+/// <c>Guid.CreateVersion7()</c> / <c>DateTimeOffset.UtcNow</c> would
+/// silently bypass the deterministic-test abstractions every command
+/// handler already threads in — which is the entire reason <c>IClock</c>
+/// and <c>IGuidFactory</c> exist (Standards 02 § Time).
+/// </remarks>
+public abstract record DomainEvent : IDomainEvent
+{
+    public required Guid EventId { get; init; }
+
+    public required DateTimeOffset OccurredAt { get; init; }
+}

backend/src/LearnStack.SharedKernel/Domain/Entity.cs

@@ -0,0 +1,110 @@
+using System.Collections.ObjectModel;
+using LearnStack.SharedKernel.Identifiers;
+
+namespace LearnStack.SharedKernel.Domain;
+
+/// <summary>
+/// Append-only / audit aggregate base. Carries identity and raises
+/// in-process <see cref="IDomainEvent"/>s; does <em>not</em> carry the
+/// <c>CreatedAt</c> / <c>UpdatedAt</c> audit columns — those belong to
+/// mutable aggregates and live on <see cref="AuditableEntity{TId}"/>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The audit subsystem's own <c>AuditEntry</c> aggregate inherits this base
+/// directly, never <see cref="AuditableEntity{TId}"/>, because audit rows
+/// are immutable once written. Architecture test
+/// <c>AuditEntry_Inherits_Entity_Not_AuditableEntity</c> guards that rule.
+/// </para>
+/// <para>
+/// Equality contract: identity-based, with three guards every aggregate
+/// inherits — transient entities (<see cref="Id"/> equal to
+/// <c>default(TId)</c>) are never equal to each other (reference equality
+/// is the only match), runtime-type mismatches are never equal even when
+/// the underlying ID matches, and the hash code partitions transient
+/// instances apart so EF Core's change-tracker identity map and any
+/// <c>HashSet</c> in a collection navigation behave correctly.
+/// </para>
+/// <para>
+/// Domain-event collection state is lazily allocated: the backing
+/// <c>List</c> and its <see cref="ReadOnlyCollection{T}"/> view are only
+/// created on first raise or first read. EF Core materialises every loaded
+/// aggregate through the parameterless ctor on read paths; the lazy
+/// approach keeps materialisation allocation-free for the common
+/// query case (paginated reads, projections), and pays the allocation only
+/// when an aggregate actually raises events (command paths).
+/// </para>
+/// </remarks>
+public abstract class Entity<TId> : IHasId<TId>, IHasDomainEvents
+    where TId : struct, IStronglyTypedId<Guid>
+{
+    private List<IDomainEvent>? _domainEvents;
+    private ReadOnlyCollection<IDomainEvent>? _domainEventsView;
+
+    protected Entity(TId id)
+    {
+        Id = id;
+    }
+
+    // EF Core / ORM materialization ctor.
+    protected Entity()
+    {
+    }
+
+    public TId Id { get; protected init; }
+
+    /// <summary>
+    /// In-process domain events raised since the last <see cref="ClearDomainEvents"/>.
+    /// Returns a cached <see cref="ReadOnlyCollection{T}"/> wrapper rather
+    /// than the backing <c>List</c> directly so callers cannot downcast
+    /// and mutate the collection out from under the aggregate. Both the
+    /// backing list and the wrapper are lazily allocated on first
+    /// access / first raise.
+    /// </summary>
+    public IReadOnlyCollection<IDomainEvent> DomainEvents =>
+        _domainEventsView ??= (_domainEvents ??= []).AsReadOnly();
+
+    protected void RaiseDomainEvent(IDomainEvent domainEvent)
+    {
+        ArgumentNullException.ThrowIfNull(domainEvent);
+        (_domainEvents ??= []).Add(domainEvent);
+    }
+
+    public void ClearDomainEvents() => _domainEvents?.Clear();
+
+    public override bool Equals(object? obj)
+    {
+        if (obj is not Entity<TId> other)
+        {
+            return false;
+        }
+
+        if (ReferenceEquals(this, other))
+        {
+            return true;
+        }
+
+        // Cross-type guard: a Course and a hypothetical CourseDraft that both
+        // inherit Entity<CourseId> and share an Id value are still different
+        // runtime types and must not compare equal.
+        if (GetType() != other.GetType())
+        {
+            return false;
+        }
+
+        // Transient guard: two newly-constructed aggregates carry default(TId)
+        // until SaveChangesAsync stamps them. They must never collapse into
+        // each other in EF's change tracker or in a HashSet-backed navigation.
+        if (Id.Equals(default(TId)) || other.Id.Equals(default(TId)))
+        {
+            return false;
+        }
+
+        return Id.Equals(other.Id);
+    }
+
+    public override int GetHashCode() =>
+        Id.Equals(default(TId))
+            ? base.GetHashCode()
+            : HashCode.Combine(GetType(), Id);
+}

backend/src/LearnStack.SharedKernel/Domain/IDomainEvent.cs

@@ -0,0 +1,23 @@
+using MediatR;
+
+namespace LearnStack.SharedKernel.Domain;
+
+/// <summary>
+/// In-process domain event raised by an aggregate method. Dispatched
+/// in-process by MediatR — the cross-module integration-event path
+/// (outbox + Dapr pub/sub) is a different mechanism per
+/// <see href="../../../../docs/decisions/0010-cross-module-communication.md">ADR-0010</see>.
+/// </summary>
+public interface IDomainEvent : INotification
+{
+    /// <summary>
+    /// Unique event identifier. UUIDv7 so insertion-order matches occurrence
+    /// order when an event is persisted for replay or debugging.
+    /// </summary>
+    Guid EventId { get; }
+
+    /// <summary>
+    /// UTC instant the event was raised.
+    /// </summary>
+    DateTimeOffset OccurredAt { get; }
+}

backend/src/LearnStack.SharedKernel/Domain/IHasDomainEvents.cs

@@ -0,0 +1,13 @@
+namespace LearnStack.SharedKernel.Domain;
+
+/// <summary>
+/// Marker every entity that raises <see cref="IDomainEvent"/> implements.
+/// The unit-of-work walks tracked entities, drains the events, and hands
+/// them to MediatR's in-process publisher on commit.
+/// </summary>
+public interface IHasDomainEvents
+{
+    IReadOnlyCollection<IDomainEvent> DomainEvents { get; }
+
+    void ClearDomainEvents();
+}

backend/src/LearnStack.SharedKernel/Identifiers/FixedGuidFactory.cs

@@ -0,0 +1,45 @@
+namespace LearnStack.SharedKernel.Identifiers;
+
+/// <summary>
+/// Deterministic <see cref="IGuidFactory"/> for tests. Returns the supplied
+/// sequence in order; throws <see cref="InvalidOperationException"/> once
+/// the sequence is exhausted so tests fail loud rather than silently
+/// reusing a default value.
+/// </summary>
+/// <remarks>
+/// <see cref="NewUuidV7"/> and <see cref="NewUuidV4"/> draw from the
+/// <em>same</em> queue — the fixture does not synthesise version-7 / -4
+/// shapes from the supplied <see cref="Guid"/>s. Callers that need to
+/// assert <c>guid.Version == 7</c> (or 4) seed the queue with
+/// version-appropriate values (e.g. <c>Guid.CreateVersion7()</c> minted
+/// at test setup) so the fixture's output is the exact <see cref="Guid"/>
+/// the test passes in. This keeps the fixture trivial; the production
+/// <see cref="SystemGuidFactory"/> is where the version contract is
+/// enforced.
+/// </remarks>
+public sealed class FixedGuidFactory : IGuidFactory
+{
+    private readonly Queue<Guid> _sequence;
+
+    public FixedGuidFactory(params Guid[] sequence)
+    {
+        ArgumentNullException.ThrowIfNull(sequence);
+        _sequence = new Queue<Guid>(sequence);
+    }
+
+    public Guid NewUuidV7() => Dequeue();
+
+    public Guid NewUuidV4() => Dequeue();
+
+    private Guid Dequeue()
+    {
+        if (_sequence.Count == 0)
+        {
+            throw new InvalidOperationException(
+                "FixedGuidFactory sequence exhausted. Construct with enough GUIDs " +
+                "for the test, or switch to a different fixture.");
+        }
+
+        return _sequence.Dequeue();
+    }
+}

backend/src/LearnStack.SharedKernel/Identifiers/IAggregateRoot.cs

@@ -0,0 +1,16 @@
+namespace LearnStack.SharedKernel.Identifiers;
+
+/// <summary>
+/// Marker for the root entity of an aggregate. Repositories accept and
+/// return only aggregate roots; entities inside an aggregate are reached
+/// through the root.
+/// </summary>
+/// <typeparam name="TId">
+/// The aggregate's strongly-typed identifier — per ADR-0023 every aggregate
+/// root carries an <see cref="IStronglyTypedId{TKey}"/>-shaped Vogen-emitted
+/// ID over <see cref="Guid"/>.
+/// </typeparam>
+public interface IAggregateRoot<out TId> : IHasId<TId>
+    where TId : struct, IStronglyTypedId<Guid>
+{
+}