Add query-plan (Specification pattern) support for EF Core

[jeremydmiller]

Summary

Phase 1 of #2505. Introduces Wolverine.EntityFrameworkCore.IQueryPlan<TDbContext, TResult> plus convenience base classes — the Specification pattern implemented as a first-class concept, patterned after Marten's IQueryPlan and Ardalis.Specification.

This fills the gap between [Entity] (primary-key lookup only) and a full repository/adapter layer. Handlers can now encapsulate reusable LINQ over a DbContext in a testable class, without any code generation or DI plumbing.

API

// Interface — minimal, matches Marten's shape
public interface IQueryPlan<in TDbContext, TResult> where TDbContext : DbContext
{
    Task<TResult> FetchAsync(TDbContext dbContext, CancellationToken cancellation);
}

// Convenience base: single result via FirstOrDefaultAsync
public abstract class QueryPlan<TDb, TEntity> : IQueryPlan<TDb, TEntity?>
    where TDb : DbContext where TEntity : class
{
    public abstract IQueryable<TEntity> Query(TDb db);
}

// Convenience base: list result via ToListAsync
public abstract class QueryListPlan<TDb, TEntity> : IQueryPlan<TDb, IReadOnlyList<TEntity>>
    where TDb : DbContext where TEntity : class
{
    public abstract IQueryable<TEntity> Query(TDb db);
}

// Sugar on DbContext (mirrors Marten's session.QueryByPlanAsync)
await db.QueryByPlanAsync(new ActiveOrderForCustomer(customerId), ct);

User code

public class ActiveOrderForCustomer(Guid customerId) : QueryPlan<OrderDbContext, Order>
{
    public override IQueryable<Order> Query(OrderDbContext db)
        => db.Orders.Where(x => x.CustomerId == customerId && !x.IsArchived)
                    .OrderByDescending(x => x.CreatedAt);
}

public static async Task Handle(ApproveOrder msg, OrderDbContext db, CancellationToken ct)
{
    var order = await db.QueryByPlanAsync(new ActiveOrderForCustomer(msg.CustomerId), ct);
    order?.Approve();
}

Design notes

• Naming matches Marten (IQueryPlan / QueryPlan / QueryListPlan) rather than ISpecification — consistency inside the Critter Stack wins, and avoids conflict with users already using Ardalis.Specification
• No code generation — plans are plain classes. Zero DI registration, zero source generators, zero runtime reflection
• Full IQueryable<T> surface — no custom DSL to learn. Include, OrderBy, Select, Skip, Take, projection to DTOs all work
• Testable in isolation — unit tests use EF Core's in-memory provider, no host required
• Multi-tenancy compatible — the plan receives whatever DbContext the handler receives (already tenant-scoped by existing middleware)

Out of scope (deferred to follow-up)

• Phase 2: [FromQueryPlan(typeof(TPlan))] parameter attribute that constructs the plan from message fields at codegen time (mirrors how [Entity] resolves its identity). Worth its own PR once the core shape is settled.
• Phase 3: batched query plan (if there's demand — existing BatchedLoadEntityFrame infrastructure is the template)

Files

• New under src/Persistence/Wolverine.EntityFrameworkCore/QueryPlans/: IQueryPlan.cs, QueryPlan.cs, QueryListPlan.cs, QueryPlanExtensions.cs
• New tests under src/Persistence/EfCoreTests/QueryPlans/: QueryPlan_specs.cs (9 unit tests), QueryPlan_end_to_end.cs (1 SQL Server integration test)
• New docs: docs/guide/durability/efcore/query-plans.md + nav entry in .vitepress/config.mts

Test plan

• 9 unit tests against EF Core in-memory provider — constructor parameters, empty results, null results, extension method, ordering, null-arg validation
• 1 end-to-end integration test: handler consumes a plan against real SQL Server + Wolverine's transactional middleware; verifies downstream SaveChangesAsync commits the mutations the plan's results triggered
• 18 existing batch_query_tests + end_to_end_efcore_persistence tests still pass (no regressions)

🤖 Generated with Claude Code