Feat: Carrier class optimization for PrebuiltDispatch chains

src/Quarry.Benchmarks/Benchmarks/AggregateBenchmarks.cs

@@ -33,7 +33,7 @@ public async Task<int> EfCore_Count()
     [Benchmark]
     public async Task<int> Quarry_Count()
     {
-        return await QuarryDb.Users
+        return await QuarryDb.Users()
             .Select(u => Sql.Count())
             .ExecuteScalarAsync<int>();
     }
@@ -64,7 +64,7 @@ public async Task<decimal> EfCore_Sum()
     [Benchmark]
     public async Task<decimal> Quarry_Sum()
     {
-        return await QuarryDb.Orders
+        return await QuarryDb.Orders()
             .Select(o => Sql.Sum(o.Total))
             .ExecuteScalarAsync<decimal>();
     }
@@ -95,7 +95,7 @@ public async Task<decimal> EfCore_Avg()
     [Benchmark]
     public async Task<decimal> Quarry_Avg()
     {
-        return await QuarryDb.Orders
+        return await QuarryDb.Orders()
             .Select(o => Sql.Avg(o.Total))
             .ExecuteScalarAsync<decimal>();
     }

src/Quarry.Benchmarks/Benchmarks/ComplexQueryBenchmarks.cs

@@ -61,7 +61,7 @@ public async Task<List<UserOrderDto>> EfCore_JoinFilterPaginate()
     [Benchmark]
     public async Task<List<UserOrderDto>> Quarry_JoinFilterPaginate()
     {
-        return await QuarryDb.Users
+        return await QuarryDb.Users()
             .Where(u => u.IsActive)
             .Join<Order>((u, o) => u.UserId == o.UserId.Id)
             .Select((u, o) => new UserOrderDto
@@ -116,7 +116,7 @@ public async Task<int> EfCore_MultiJoinAggregate()
     [Benchmark]
     public async Task<int> Quarry_MultiJoinAggregate()
     {
-        var results = await QuarryDb.Users
+        var results = await QuarryDb.Users()
             .Where(u => u.IsActive)
             .Join<Order>((u, o) => u.UserId == o.UserId.Id)
             .Join<OrderItem>((u, o, oi) => o.OrderId == oi.OrderId.Id)

src/Quarry.Benchmarks/Benchmarks/FilterBenchmarks.cs

@@ -50,7 +50,7 @@ public async Task<List<EfUser>> EfCore_WhereActive()
     [Benchmark]
     public async Task<List<EfUser>> Quarry_WhereActive()
     {
-        return await QuarryDb.Users
+        return await QuarryDb.Users()
             .Where(u => u.IsActive)
             .Select(u => new EfUser
             {
@@ -109,7 +109,7 @@ public async Task<List<UserSummaryDto>> EfCore_WhereCompound()
     [Benchmark]
     public async Task<List<UserSummaryDto>> Quarry_WhereCompound()
     {
-        return await QuarryDb.Users
+        return await QuarryDb.Users()
             .Where(u => u.IsActive)
             .Where(u => u.Email != null)
             .Select(u => new UserSummaryDto
@@ -163,7 +163,7 @@ public async Task<List<UserSummaryDto>> Quarry_WhereCompound()
     [Benchmark]
     public async Task<EfUser?> Quarry_WhereById()
     {
-        return await QuarryDb.Users
+        return await QuarryDb.Users()
             .Where(u => u.UserId == 42)
             .Select(u => new EfUser
             {

src/Quarry.Benchmarks/Benchmarks/InsertBenchmarks.cs

@@ -65,7 +65,7 @@ public async Task<int> EfCore_SingleInsert()
     [Benchmark]
     public async Task<int> Quarry_SingleInsert()
     {
-        return await QuarryDb.Insert(new User
+        return await QuarryDb.Users().Insert(new User
         {
             UserName = "BenchUser",
             Email = "bench@example.com",
@@ -134,6 +134,6 @@ public async Task<int> Quarry_BatchInsert10()
             IsActive = true,
             CreatedAt = DateTime.UtcNow
         });
-        return await QuarryDb.InsertMany(users).ExecuteNonQueryAsync();
+        return await QuarryDb.Users().InsertMany(users).ExecuteNonQueryAsync();
     }
 }

src/Quarry.Benchmarks/Benchmarks/JoinBenchmarks.cs

@@ -47,7 +47,7 @@ public async Task<List<UserOrderDto>> EfCore_InnerJoin()
     [Benchmark]
     public async Task<List<UserOrderDto>> Quarry_InnerJoin()
     {
-        return await QuarryDb.Users
+        return await QuarryDb.Users()
             .Join<Order>((u, o) => u.UserId == o.UserId.Id)
             .Select((u, o) => new UserOrderDto
             {
@@ -112,7 +112,7 @@ public async Task<List<UserOrderItemDto>> EfCore_ThreeTableJoin()
     [Benchmark]
     public async Task<List<UserOrderItemDto>> Quarry_ThreeTableJoin()
     {
-        return await QuarryDb.Users
+        return await QuarryDb.Users()
             .Join<Order>((u, o) => u.UserId == o.UserId.Id)
             .Join<OrderItem>((u, o, oi) => o.OrderId == oi.OrderId.Id)
             .Select((u, o, oi) => new UserOrderItemDto

src/Quarry.Benchmarks/Benchmarks/PaginationBenchmarks.cs

@@ -51,7 +51,7 @@ public async Task<List<EfUser>> EfCore_LimitOffset()
     [Benchmark]
     public async Task<List<EfUser>> Quarry_LimitOffset()
     {
-        return await QuarryDb.Users
+        return await QuarryDb.Users()
             .Select(u => new EfUser
             {
                 UserId = u.UserId,
@@ -108,7 +108,7 @@ public async Task<List<EfUser>> EfCore_FirstPage()
     [Benchmark]
     public async Task<List<EfUser>> Quarry_FirstPage()
     {
-        return await QuarryDb.Users
+        return await QuarryDb.Users()
             .Select(u => new EfUser
             {
                 UserId = u.UserId,

src/Quarry.Benchmarks/Benchmarks/SelectBenchmarks.cs

@@ -48,7 +48,7 @@ public async Task<List<EfUser>> EfCore_SelectAll()
     [Benchmark]
     public async Task<List<EfUser>> Quarry_SelectAll()
     {
-        return await QuarryDb.Users
+        return await QuarryDb.Users()
             .Select(u => new EfUser
             {
                 UserId = u.UserId,
@@ -105,7 +105,7 @@ public async Task<List<UserSummaryDto>> EfCore_SelectProjection()
     [Benchmark]
     public async Task<List<UserSummaryDto>> Quarry_SelectProjection()
     {
-        return await QuarryDb.Users
+        return await QuarryDb.Users()
             .Select(u => new UserSummaryDto
             {
                 UserId = u.UserId,

src/Quarry.Benchmarks/Benchmarks/StringOpBenchmarks.cs

@@ -53,7 +53,7 @@ public async Task<List<UserSummaryDto>> EfCore_Contains()
     [Benchmark]
     public async Task<List<UserSummaryDto>> Quarry_Contains()
     {
-        return await QuarryDb.Users
+        return await QuarryDb.Users()
             .Where(u => u.UserName.Contains("User05"))
             .Select(u => new UserSummaryDto
             {
@@ -109,7 +109,7 @@ public async Task<List<UserSummaryDto>> EfCore_StartsWith()
     [Benchmark]
     public async Task<List<UserSummaryDto>> Quarry_StartsWith()
     {
-        return await QuarryDb.Users
+        return await QuarryDb.Users()
             .Where(u => u.UserName.StartsWith("User0"))
             .Select(u => new UserSummaryDto
             {

src/Quarry.Benchmarks/Context/BenchDb.cs

@@ -5,7 +5,7 @@ namespace Quarry.Benchmarks.Context;
 [QuarryContext(Dialect = SqlDialect.SQLite)]
 public partial class BenchDb : QuarryContext
 {
-    public partial IQueryBuilder<User> Users { get; }
-    public partial IQueryBuilder<Order> Orders { get; }
-    public partial IQueryBuilder<OrderItem> OrderItems { get; }
+    public partial IEntityAccessor<User> Users();
+    public partial IEntityAccessor<Order> Orders();
+    public partial IEntityAccessor<OrderItem> OrderItems();
 }

src/Quarry.Generator/DiagnosticDescriptors.cs

@@ -444,6 +444,21 @@ internal static class DiagnosticDescriptors
                      "The existing runtime SqlBuilder path will be used. This is not an error — " +
                      "consider restructuring the query to enable optimization.");
 
+    /// <summary>
+    /// QRY033: Forked query chain — builder variable consumed by multiple execution paths.
+    /// Severity: Error
+    /// </summary>
+    public static readonly DiagnosticDescriptor ForkedQueryChain = new(
+        id: "QRY033",
+        title: "Forked query chain",
+        messageFormat: "Query builder variable '{0}' is consumed by multiple execution paths. Each execution path must use its own builder chain expression.",
+        category: Category,
+        defaultSeverity: DiagnosticSeverity.Error,
+        isEnabledByDefault: true,
+        description: "A query builder variable is used as the receiver for multiple execution-terminating calls " +
+                     "(e.g., ExecuteFetchAllAsync). Each execution path must use its own independent builder chain " +
+                     "to avoid confusing aliasing behavior from the immutable builder contract.");
+
     // ─── Migration diagnostics (QRY050–QRY055) ────────────────────────
 
     /// <summary>

src/Quarry.Generator/Generation/CarrierClassBuilder.cs

@@ -0,0 +1,167 @@
+using System.Collections.Generic;
+using System.Linq;
+using Quarry.Generators.Models;
+
+namespace Quarry.Generators.Generation;
+
+/// <summary>
+/// Builds <see cref="CarrierClassInfo"/> from a <see cref="PrebuiltChainInfo"/>.
+/// The carrier class is a lightweight <c>file sealed class</c> that inherits from
+/// a carrier base class and declares only chain-specific fields.
+/// </summary>
+internal static class CarrierClassBuilder
+{
+    /// <summary>
+    /// Builds a CarrierClassInfo for a carrier-eligible PrebuiltDispatch chain.
+    /// Returns null if the chain cannot be carrier-optimized.
+    /// </summary>
+    public static CarrierClassInfo? Build(PrebuiltChainInfo chain, int chainIndex, string? resolvedBaseClass = null)
+    {
+        if (!chain.IsCarrierEligible)
+            return null;
+
+        var fields = new List<CarrierField>();
+
+        // Fields: typed parameters P0, P1, ...
+        foreach (var param in chain.ChainParameters)
+        {
+            fields.Add(new CarrierField($"P{param.Index}", NormalizeFieldType(param.TypeName), FieldRole.Parameter));
+        }
+
+        // Field: Mask (if chain has conditional clauses)
+        if (chain.Analysis.ConditionalClauses.Count > 0)
+        {
+            var bitCount = chain.Analysis.ConditionalClauses.Count;
+            var maskType = bitCount <= 8 ? "byte" : bitCount <= 16 ? "ushort" : "uint";
+            fields.Add(new CarrierField("Mask", maskType, FieldRole.ClauseMask));
+        }
+
+        // Fields: Limit/Offset (if chain has runtime pagination values)
+        foreach (var clause in chain.Analysis.Clauses)
+        {
+            if (clause.Role == ClauseRole.Limit)
+                fields.Add(new CarrierField("Limit", "int", FieldRole.Limit));
+            if (clause.Role == ClauseRole.Offset)
+                fields.Add(new CarrierField("Offset", "int", FieldRole.Offset));
+        }
+
+        // Field: Timeout (if chain contains WithTimeout)
+        if (chain.Analysis.Clauses.Any(c => c.Role == ClauseRole.WithTimeout))
+            fields.Add(new CarrierField("Timeout", "TimeSpan?", FieldRole.Timeout));
+
+        // Field: Entity (for insert chains — stores the entity passed to .Insert())
+        if (chain.QueryKind == QueryKind.Insert)
+        {
+            var entityType = InterceptorCodeGenerator.GetShortTypeName(chain.EntityTypeName);
+            fields.Add(new CarrierField("Entity", entityType + "?", FieldRole.Entity));
+        }
+
+        // Static FieldInfo cache fields — only for captured params needing expression tree extraction
+        var staticFields = new List<CarrierStaticField>();
+        foreach (var param in chain.ChainParameters)
+        {
+            if (param.NeedsFieldInfoCache)
+                staticFields.Add(new CarrierStaticField($"F{param.Index}", "FieldInfo?", param.Index));
+        }
+
+        // Determine base class from chain shape (caller may provide pre-resolved base)
+        var baseClassName = resolvedBaseClass ?? SelectBaseClass(chain);
+
+        var className = $"Chain_{chainIndex}";
+
+        return new CarrierClassInfo(
+            className: className,
+            implementedInterfaces: new[] { baseClassName },
+            fields: fields,
+            deadMethods: System.Array.Empty<CarrierInterfaceStub>(),
+            staticFields: staticFields);
+    }
+
+    /// <summary>
+    /// Selects the appropriate carrier base class based on the chain's shape
+    /// (join count, whether it has a Select projection).
+    /// </summary>
+    private static string SelectBaseClass(PrebuiltChainInfo chain)
+    {
+        var entityType = InterceptorCodeGenerator.GetShortTypeName(chain.EntityTypeName);
+        var hasSelect = chain.Analysis.Clauses.Any(c => c.Role == ClauseRole.Select);
+        var joinCount = chain.IsJoinChain ? (chain.JoinedEntityTypeNames?.Count ?? 1) - 1 : 0;
+
+        if (joinCount == 0)
+        {
+            if (hasSelect && chain.ResultTypeName != null)
+            {
+                var resultType = InterceptorCodeGenerator.GetShortTypeName(chain.ResultTypeName);
+                return $"CarrierBase<{entityType}, {resultType}>";
+            }
+            return $"CarrierBase<{entityType}>";
+        }
+
+        var joinedTypes = chain.JoinedEntityTypeNames!.Select(InterceptorCodeGenerator.GetShortTypeName).ToArray();
+        var joinedTypesStr = string.Join(", ", joinedTypes);
+
+        if (hasSelect && chain.ResultTypeName != null)
+        {
+            var resultType = InterceptorCodeGenerator.GetShortTypeName(chain.ResultTypeName);
+            return joinCount switch
+            {
+                1 => $"JoinedCarrierBase<{joinedTypesStr}, {resultType}>",
+                2 => $"JoinedCarrierBase3<{joinedTypesStr}, {resultType}>",
+                3 => $"JoinedCarrierBase4<{joinedTypesStr}, {resultType}>",
+                _ => $"JoinedCarrierBase<{joinedTypesStr}, {resultType}>"
+            };
+        }
+
+        return joinCount switch
+        {
+            1 => $"JoinedCarrierBase<{joinedTypesStr}>",
+            2 => $"JoinedCarrierBase3<{joinedTypesStr}>",
+            3 => $"JoinedCarrierBase4<{joinedTypesStr}>",
+            _ => $"JoinedCarrierBase<{joinedTypesStr}>"
+        };
+    }
+
+    /// <summary>
+    /// Known value types that don't need nullable annotation.
+    /// </summary>
+    private static readonly HashSet<string> ValueTypes = new(System.StringComparer.Ordinal)
+    {
+        "int", "long", "short", "byte", "sbyte", "uint", "ulong", "ushort",
+        "float", "double", "decimal", "bool", "char",
+        "DateTime", "DateTimeOffset", "TimeSpan", "Guid", "DateOnly", "TimeOnly",
+        "Int32", "Int64", "Int16", "Byte", "SByte", "UInt32", "UInt64", "UInt16",
+        "Single", "Double", "Decimal", "Boolean", "Char"
+    };
+
+    /// <summary>
+    /// Normalizes a parameter type for carrier field emission.
+    /// - Normalizes <c>Nullable&lt;T&gt;</c> to <c>T?</c>
+    /// - Appends <c>?</c> to reference types (non-value-types without existing <c>?</c>)
+    ///   to suppress nullable warnings in <c>#nullable enable</c> context
+    /// </summary>
+    private static string NormalizeFieldType(string typeName)
+    {
+        // Normalize Nullable<T> → T?
+        if (typeName.StartsWith("System.Nullable<") || typeName.StartsWith("Nullable<"))
+        {
+            var inner = typeName.Substring(typeName.IndexOf('<') + 1).TrimEnd('>');
+            return inner + "?";
+        }
+
+        // Already nullable — pass through
+        if (typeName.EndsWith("?"))
+            return typeName;
+
+        // Value types don't need ?
+        if (ValueTypes.Contains(typeName))
+            return typeName;
+
+        // Enum types (usually PascalCase without dots) — assume value type, pass through
+        // Generic types, array types — pass through (complex to analyze)
+        if (typeName.Contains('<') || typeName.Contains('[') || typeName.Contains('.'))
+            return typeName;
+
+        // Reference types (string, class names) — append ? for nullable context
+        return typeName + "?";
+    }
+}