no-mistakes(document): Sync field.map docs to final emission; fix CS8605s

Author: dmealing

CHANGELOG.md

@@ -55,7 +55,16 @@ It now emits an explicit jsonb column type plus a shared converter/comparer pair
 entities, read-only projections and flattened value-object members alike. The comparer is
 load-bearing, not decoration: EF snapshots a value-converted property by reference, so a
 converter alone would leave an in-place `entity.Labels["k"] = v` undetected and the UPDATE
-would never fire.
+would never fire. Two details of the emitted shape: the property's NULLABILITY follows the
+column — a `@required` map is a non-null dictionary with an empty-dictionary initializer,
+any other map a nullable dictionary with no initializer, because the migration's column is
+nullable by default and a non-nullable property over it makes EF Core 8 skip the shaper's
+NULL check (one NULL cell — a row written by another port, or before the field existed —
+would 500 every read arm), and NULL stays distinct from a present `{}`. And the shared
+serializer options carry a `JsonStringEnumConverter`, so a `field.enum` member of the map's
+value object persists as its member SYMBOL — the rule the owned-`field.object` jsonb column
+already follows; System.Text.Json's default int ordinal is a value no sibling port writes
+for the same declared field.
 
 **Scope.** No runtime persistence layer reads or writes a map except Python's
 `ObjectManager`, and no persistence- or api-contract-conformance corpus exercises

server/csharp/MetaObjects.Codegen.Tests/MapFieldCodegenTests.cs

@@ -267,9 +267,9 @@ public void MapJsonb_comparer_hash_and_snapshot_tolerate_a_null_dictionary()
         // A null map hashes to a stable constant and snapshots as null, on BOTH value-type
         // arms -- Hash used to dereference v.Count and the scalar Snap arm passed v to the
         // Dictionary copy constructor, so a null map threw inside EF change tracking.
-        Assert.Equal(0, (int)InvokeLambda(scalar, "HashCodeExpression", (object?)null));
+        Assert.Equal(0, (int)InvokeLambda(scalar, "HashCodeExpression", (object?)null)!);
         Assert.Null(InvokeLambda(scalar, "SnapshotExpression", (object?)null));
-        Assert.Equal(0, (int)InvokeLambda(objectValued, "HashCodeExpression", (object?)null));
+        Assert.Equal(0, (int)InvokeLambda(objectValued, "HashCodeExpression", (object?)null)!);
         Assert.Null(InvokeLambda(objectValued, "SnapshotExpression", (object?)null));
 
         // Semantics beyond null handling are unchanged: entry-wise order-independent

server/csharp/MetaObjects.Codegen/Generators/DbContextGenerator.cs

@@ -714,6 +714,14 @@ private static string MapValueTypeRef(MetaField f, GenContext ctx)
     /// <c>EqualityComparer&lt;T&gt;.Default</c> with no serialization at all, while a value-object
     /// value still falls through to a JSON compare because the generated POCO is a class and
     /// compares by reference. The snapshot deep-copies only when the value type needs it.</para>
+    /// <para>The shared <c>Options</c> instance the helper emits carries a
+    /// <c>JsonStringEnumConverter</c> so a <c>field.enum</c> member of the map's value object
+    /// serializes as its member SYMBOL — the rule <see cref="JsonEnumConversions"/> states for
+    /// the owned-<c>field.object</c> jsonb path, for the same reason: System.Text.Json's
+    /// default is the enum's int ORDINAL, which no sibling port writes for the same declared
+    /// field, and <c>@intValueMap</c> is a column-storage concern that reaches nothing inside
+    /// a JSON document. One shared instance serves the converter and the Eq/Snap JSON arms,
+    /// so every arm encodes enums identically.</para>
     /// <para>Fully qualified throughout: the generated file's usings are a fixed set
     /// (<see cref="EmitUsings"/>), and widening it would change byte-identical output for
     /// every model.</para>