fix: address Copilot review feedback on PR #31

- Reject static backing fields in Pattern B of ProjectablePatternRecognizer.
  A static field would share materialized state across all instances, breaking
  per-entity semantics. Adds a snapshot test for the EXP0022 diagnostic.

- Register ExpressiveMongoIgnoreConvention from the AsExpressive extension path
  (not just the ExpressiveMongoCollection<T> constructor). Document the ordering
  constraint with MongoDB's eager class-map caching, and recommend calling
  ExpressiveMongoIgnoreConvention.EnsureRegistered() at startup.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: koenbeuk

docs/guide/integrations/mongodb.md

@@ -45,9 +45,24 @@ No custom MQL is emitted — MongoDB's own translator does all the heavy lifting
 
 ## `[Expressive]` Properties Are Unmapped from BSON
 
-ExpressiveSharp registers a MongoDB `IClassMapConvention` that unmaps every `[Expressive]`-decorated property from the BSON class map, so the property's backing field is not persisted to documents. This matters most for [Projectable properties](../../reference/projectable-properties), which have a writable `init` accessor and would otherwise be serialized as a real BSON field.
+ExpressiveSharp provides a MongoDB `IClassMapConvention` that unmaps every `[Expressive]`-decorated property from the BSON class map, so the property's backing field is not persisted to documents. This matters most for [Projectable properties](../../reference/projectable-properties), which have a writable `init` accessor and would otherwise be serialized as a real BSON field.
 
-The convention is registered automatically the first time you construct an `ExpressiveMongoCollection<T>` or call `.AsExpressive()` on a collection. No opt-in is required.
+::: warning Ordering constraint
+MongoDB builds and caches a class map the first time you call `IMongoDatabase.GetCollection<T>()` for a given `T`. A convention registered *after* that call does not apply to the cached map. If any of your document types use `[Expressive]`, register the convention before the first `GetCollection<T>` call:
+
+```csharp
+using ExpressiveSharp.MongoDB.Infrastructure;
+
+// At application startup, before any GetCollection<T>:
+ExpressiveMongoIgnoreConvention.EnsureRegistered();
+
+var client = new MongoClient(connectionString);
+var db = client.GetDatabase("shop");
+var customers = db.GetCollection<Customer>("customers");  // class map built now
+```
+
+The convention is also registered automatically when you construct `ExpressiveMongoCollection<T>` or call `collection.AsExpressive()` — but only if that happens before any `GetCollection<T>` call for a type with `[Expressive]` properties. The explicit `EnsureRegistered()` call is the most reliable pattern.
+:::
 
 ## Async Methods
 

src/ExpressiveSharp.Generator/Interpretation/ProjectablePatternRecognizer.cs

@@ -148,8 +148,11 @@ private static bool MatchesPatternAOrB(
             return true;
         }
 
-        // Pattern B: manually declared private nullable backing field on the same type.
-        if (field.DeclaredAccessibility != Accessibility.Private
+        // Pattern B: manually declared private *instance* nullable backing field on the same type.
+        // A static backing field is explicitly rejected because it would share materialized state
+        // across all instances of the containing type, breaking per-entity materialization semantics.
+        if (field.IsStatic
+            || field.DeclaredAccessibility != Accessibility.Private
             || !SymbolEqualityComparer.Default.Equals(field.ContainingType, property.ContainingType))
         {
             ReportGetAccessorPattern(context, diagnosticLocation,

src/ExpressiveSharp.MongoDB/ExpressiveMongoCollection.cs

@@ -40,8 +40,10 @@ public ExpressiveMongoCollection(IMongoCollection<TDocument> inner, ExpressiveOp
         _inner = inner ?? throw new ArgumentNullException(nameof(inner));
         _options = options ?? MongoExpressiveOptions.CreateDefault();
 
-        // Unmap [Expressive] (including Projectable) properties from BSON serialization
-        // so the backing field is not persisted to documents.
+        // Idempotent registration; belt-and-braces for code paths that access
+        // `Inner` directly for writes (InsertOne/ReplaceOne/…) without ever
+        // going through `AsQueryable`. The `AsExpressive` extension registers
+        // the convention on the query path.
         ExpressiveMongoIgnoreConvention.EnsureRegistered();
     }
 

src/ExpressiveSharp.MongoDB/Extensions/MongoExpressiveExtensions.cs

@@ -25,6 +25,12 @@ public static IExpressiveMongoQueryable<T> AsExpressive<T>(
         this IQueryable<T> source,
         ExpressiveOptions? options = null)
     {
+        // Idempotent; cheap on subsequent calls via an Interlocked.Exchange guard.
+        // Registering here (rather than in ExpressiveMongoCollection's constructor)
+        // guarantees the BSON class-map convention fires on the common
+        // `collection.AsExpressive()` entry point too.
+        ExpressiveMongoIgnoreConvention.EnsureRegistered();
+
         var mongoProvider = source.Provider as IMongoQueryProvider
             ?? throw new ArgumentException(
                 "The source queryable's Provider must implement IMongoQueryProvider. " +
@@ -52,6 +58,13 @@ public static IExpressiveMongoQueryable<T> AsExpressive<T>(
         ExpressiveOptions? options = null,
         AggregateOptions? aggregateOptions = null)
     {
+        // MongoDB's AsQueryable() builds the BSON class map eagerly to prepare the
+        // aggregation pipeline. We must register our ignore convention *before* that
+        // call, otherwise the class map for T is constructed with the default auto-map
+        // behavior that includes writable [Expressive] properties as BSON fields —
+        // persisting backing-field state to the document.
+        ExpressiveMongoIgnoreConvention.EnsureRegistered();
+
         var queryable = aggregateOptions is not null
             ? collection.AsQueryable(aggregateOptions)
             : collection.AsQueryable();

src/ExpressiveSharp.MongoDB/Infrastructure/ExpressiveMongoIgnoreConvention.cs

@@ -34,20 +34,30 @@ public sealed class ExpressiveMongoIgnoreConvention : ConventionBase, IClassMapC
 
     public ExpressiveMongoIgnoreConvention() : base("ExpressiveSharpIgnore") { }
 
+    /// <summary>
+    /// Runs during class-map construction. Inspects the class's CLR properties directly
+    /// (instead of <see cref="BsonClassMap.DeclaredMemberMaps"/>, which may not be populated
+    /// yet at this stage) and unmaps any that carry <see cref="ExpressiveAttribute"/>.
+    /// </summary>
     public void Apply(BsonClassMap classMap)
     {
-        if (classMap is null) throw new ArgumentNullException(nameof(classMap));
+        ArgumentNullException.ThrowIfNull(classMap);
 
-        // Walk the class map's already-auto-mapped members and remove any whose underlying
-        // PropertyInfo carries [Expressive]. Using DeclaredMemberMaps (not AllMemberMaps) to
-        // only touch members declared on this specific class; inherited ones will be unmapped
-        // when the base class's map is built.
-        foreach (var memberMap in classMap.DeclaredMemberMaps.ToArray())
+        foreach (var property in classMap.ClassType.GetProperties(
+            BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic))
         {
-            if (memberMap.MemberInfo is not PropertyInfo property) continue;
-            if (property.GetCustomAttribute<ExpressiveAttribute>(inherit: false) is null) continue;
+            // Only unmap properties declared on this exact type; inherited ones are handled
+            // by the base class's own class-map convention pass.
+            if (property.DeclaringType != classMap.ClassType)
+            {
+                continue;
+            }
+            if (property.GetCustomAttribute<ExpressiveAttribute>(inherit: false) is null)
+            {
+                continue;
+            }
 
-            classMap.UnmapMember(memberMap.MemberInfo);
+            classMap.UnmapProperty(property.Name);
         }
     }
 
@@ -60,10 +70,25 @@ public void Apply(BsonClassMap classMap)
     /// <see cref="ConventionRegistry"/>. Subsequent calls are no-ops.
     /// </summary>
     /// <remarks>
+    /// <para>
+    /// <b>Ordering matters.</b> MongoDB builds and caches a <see cref="BsonClassMap"/> for a
+    /// document type on the first call to <c>IMongoDatabase.GetCollection&lt;T&gt;()</c>. A
+    /// convention registered <i>after</i> that call does not apply to the cached map; the
+    /// <c>[Expressive]</c> properties will still be serialized to BSON.
+    /// </para>
+    /// <para>
+    /// Call this method once at application startup, before any <c>GetCollection&lt;T&gt;</c>
+    /// call for a type that has <c>[Expressive]</c> properties. Alternatively, wrap the
+    /// collection in <see cref="ExpressiveMongoCollection{TDocument}"/> or call
+    /// <c>collection.AsExpressive()</c> before any other collection handle is obtained; both
+    /// of those paths call this method.
+    /// </para>
+    /// <para>
     /// The filter predicate returns <c>true</c> for every type — the convention's
     /// <see cref="Apply(BsonClassMap)"/> is a no-op for classes without <c>[Expressive]</c>
     /// properties, so applying it globally is harmless and avoids subtle ordering issues
     /// where a type-level predicate is evaluated before attribute metadata is visible.
+    /// </para>
     /// </remarks>
     public static void EnsureRegistered()
     {

tests/ExpressiveSharp.Generator.Tests/ExpressiveGenerator/ProjectableTests.cs

@@ -263,6 +263,36 @@ public string FullName
             "Expected either EXP0022 (pattern mismatch) or EXP0025 (backing field type mismatch)");
     }
 
+    [TestMethod]
+    public void StaticBackingField_EXP0022()
+    {
+        // A static backing field would share materialized state across all instances.
+        // It must be rejected so per-entity semantics are preserved.
+        var compilation = CreateCompilation(
+            """
+            namespace Foo {
+                class User {
+                    public string FirstName { get; set; } = "";
+                    public string LastName  { get; set; } = "";
+
+                    private static string? _shared;
+
+                    [Expressive(Projectable = true)]
+                    public string FullName
+                    {
+                        get => _shared ?? (LastName + ", " + FirstName);
+                        init => _shared = value;
+                    }
+                }
+            }
+            """);
+        var result = RunExpressiveGenerator(compilation);
+
+        Assert.IsTrue(
+            result.Diagnostics.Any(d => d.Id == "EXP0022"),
+            "Static backing fields must be rejected with EXP0022 (pattern mismatch)");
+    }
+
     [TestMethod]
     public void RequiredModifier_EXP0026()
     {

tests/ExpressiveSharp.MongoDB.IntegrationTests/Tests/ProjectableMongoIgnoreTests.cs

@@ -26,7 +26,12 @@ public async Task InitMongo()
         if (!MongoContainerFixture.IsDockerAvailable)
             Assert.Inconclusive("Docker not available");
 
-        // Register the ignore convention BEFORE any class map could be implicitly built.
+        // IMPORTANT: The ignore convention must be registered BEFORE the first call to
+        // IMongoDatabase.GetCollection<T>(), which builds and caches the BSON class map for
+        // T eagerly. A convention registered afterward would not apply to the cached map.
+        // Users who want [Expressive] properties unmapped from BSON must either call
+        // EnsureRegistered() before accessing collections, or go through
+        // ExpressiveMongoCollection<T>/AsExpressive() *before* the first GetCollection<T>.
         ExpressiveMongoIgnoreConvention.EnsureRegistered();
 
         _client = new MongoClient(MongoContainerFixture.ConnectionString);