Add cross-project polymorphism mappings

Author: xoofx

readme.md

@@ -13,6 +13,7 @@ Tomlyn is a high-performance .NET [TOML](https://toml.io/en/) 1.1 parser, round-
 - **`System.Text.Json`-style API**: familiar surface with `TomlSerializer`, `TomlSerializerOptions`, `TomlTypeInfo<T>`
 - **TOML 1.1.0 only**: Tomlyn v1 targets [TOML 1.1.0](https://toml.io/en/v1.1.0) and does **not** support TOML 1.0
 - **Source generation**: NativeAOT / trimming friendly via `TomlSerializerContext` and `[TomlSerializable]` roots
+- **Cross-project polymorphism**: register derived types at runtime or on a source-generated context when base and derived types live in different assemblies
 - **`System.Text.Json` attribute interop**: reuse `[JsonPropertyName]`, `[JsonIgnore]`, `[JsonRequired]`, `[JsonConstructor]`, `[JsonObjectCreationHandling]`, and polymorphism attributes
 - **Flexible collection input**: opt a collection member into accepting either a single TOML value or an array via `[TomlSingleOrArray]`
 - **Allocation-free parsing pipeline**: incremental `TomlLexer` → `TomlParser` with precise spans for errors
@@ -114,6 +115,47 @@ var config = TomlSerializer.Deserialize(toml, MyTomlContext.Default.MyConfig);
 var tomlOut = TomlSerializer.Serialize(config, MyTomlContext.Default.MyConfig);
 ```
 
+### Cross-Project Polymorphism
+
+When a base type lives in one project and derived types live in another, you can register derived types without putting `[TomlDerivedType]` on the base type.
+
+**Reflection path**:
+
+```csharp
+using Tomlyn;
+
+var options = new TomlSerializerOptions
+{
+    PolymorphismOptions = new TomlPolymorphismOptions
+    {
+        TypeDiscriminatorPropertyName = "kind",
+        DerivedTypeMappings = new Dictionary<Type, IReadOnlyList<TomlDerivedType>>
+        {
+            [typeof(Animal)] =
+            [
+                new(typeof(Cat), "cat"),
+                new(typeof(Dog), "dog"),
+            ],
+        },
+    },
+};
+```
+
+**Source generation path**:
+
+```csharp
+using Tomlyn.Serialization;
+
+[TomlSerializable(typeof(Animal))]
+[TomlDerivedTypeMapping(typeof(Animal), typeof(Cat), "cat")]
+[TomlDerivedTypeMapping(typeof(Animal), typeof(Dog), "dog")]
+internal partial class MyTomlContext : TomlSerializerContext
+{
+}
+```
+
+Use `TomlPolymorphismOptions.DerivedTypeMappings` and `[TomlDerivedTypeMapping]` additively with existing base-type attributes. Base-type registrations still take precedence when the same discriminator or derived type is registered more than once.
+
 ### Single Value Or Array Collections
 
 ```csharp

site/docs/serialization.md

@@ -457,7 +457,7 @@ The extension data member should be a dictionary type with string keys (e.g. `ID
 
 ## Polymorphism
 
-Tomlyn supports discriminator-based polymorphism via attributes or options.
+Tomlyn supports discriminator-based polymorphism via base-type attributes, reflection-time runtime mappings, and source-generated context mappings.
 
 ### Attribute-based
 
@@ -509,6 +509,51 @@ public abstract class Animal { /* ... */ }
 > [!NOTE]
 > When both Toml and Json polymorphic attributes are present on the same type, the Toml-specific attributes take precedence.
 
+### Cross-project runtime mappings
+
+Use [`TomlPolymorphismOptions.DerivedTypeMappings`](xref:Tomlyn.TomlPolymorphismOptions.DerivedTypeMappings) when the base type and derived types live in different projects and you're using the reflection resolver:
+
+```csharp
+using Tomlyn;
+
+var options = new TomlSerializerOptions
+{
+    PolymorphismOptions = new TomlPolymorphismOptions
+    {
+        TypeDiscriminatorPropertyName = "kind",
+        DerivedTypeMappings = new Dictionary<Type, IReadOnlyList<TomlDerivedType>>
+        {
+            [typeof(Animal)] =
+            [
+                new(typeof(Cat), "cat"),
+                new(typeof(Dog), "dog"),
+            ],
+        },
+    },
+};
+```
+
+This is especially useful for clean architecture and plugin-style applications where the base type cannot reference every concrete implementation.
+
+### Cross-project source generation mappings
+
+Use [`TomlDerivedTypeMappingAttribute`](xref:Tomlyn.Serialization.TomlDerivedTypeMappingAttribute) on a [`TomlSerializerContext`](xref:Tomlyn.Serialization.TomlSerializerContext) when you want the same pattern in NativeAOT / trimming-safe source-generated code:
+
+```csharp
+using Tomlyn.Serialization;
+
+[TomlSerializable(typeof(Animal))]
+[TomlDerivedTypeMapping(typeof(Animal), typeof(Cat), "cat")]
+[TomlDerivedTypeMapping(typeof(Animal), typeof(Dog), "dog")]
+internal partial class AnimalContext : TomlSerializerContext
+{
+}
+```
+
+Mapped derived types are discovered automatically by the generator, so they do not also need their own `[TomlSerializable]` roots.
+
+If the base type doesn't declare [`TomlPolymorphicAttribute`](xref:Tomlyn.Serialization.TomlPolymorphicAttribute) or a JSON equivalent, Tomlyn still supports the mapping and falls back to [`TomlPolymorphismOptions`](xref:Tomlyn.TomlPolymorphismOptions) for the discriminator property name and unknown-derived-type handling.
+
 ### Default derived type
 
 Register one derived type **without a discriminator** to act as the default. When a TOML table has no discriminator key (or an unknown discriminator), it deserializes as the default type. When serializing the default type, no discriminator is emitted.
@@ -593,6 +638,13 @@ The priority chain is:
 2. `JsonPolymorphicAttribute.UnknownDerivedTypeHandling` (mapped from `JsonUnknownDerivedTypeHandling`)
 3. [`TomlPolymorphismOptions.UnknownDerivedTypeHandling`](xref:Tomlyn.TomlPolymorphismOptions.UnknownDerivedTypeHandling) (global default)
 
+Derived type registrations are merged additively with this precedence:
+
+1. [`TomlDerivedTypeAttribute`](xref:Tomlyn.Serialization.TomlDerivedTypeAttribute) on the base type
+2. [`JsonDerivedTypeAttribute`](xref:System.Text.Json.Serialization.JsonDerivedTypeAttribute) on the base type
+3. [`TomlDerivedTypeMappingAttribute`](xref:Tomlyn.Serialization.TomlDerivedTypeMappingAttribute) on a source-generated context
+4. [`TomlPolymorphismOptions.DerivedTypeMappings`](xref:Tomlyn.TomlPolymorphismOptions.DerivedTypeMappings) at runtime
+
 > [!NOTE]
 > [`TomlUnknownDerivedTypeHandling.Unspecified`](xref:Tomlyn.TomlUnknownDerivedTypeHandling.Unspecified) is a sentinel value for attribute properties and **cannot** be used on [`TomlPolymorphismOptions`](xref:Tomlyn.TomlPolymorphismOptions) - doing so throws `ArgumentOutOfRangeException`.
 

site/docs/source-generation.md

@@ -38,6 +38,24 @@ Nested types referenced by the root are discovered transitively - you only need
 Set [`TomlSerializableAttribute.TypeInfoPropertyName`](xref:Tomlyn.Serialization.TomlSerializableAttribute.TypeInfoPropertyName) when you want to customize the generated property name exposed by the context.
 Source-generated deserialization also supports C# `init` and `required` members.
 
+## Cross-project polymorphism
+
+When a polymorphic base type cannot reference all of its derived types, register the derived types on the context instead of on the base type:
+
+```csharp
+using Tomlyn.Serialization;
+
+[TomlSerializable(typeof(Animal))]
+[TomlDerivedTypeMapping(typeof(Animal), typeof(Cat), "cat")]
+[TomlDerivedTypeMapping(typeof(Animal), typeof(Dog), "dog")]
+internal partial class AnimalContext : TomlSerializerContext
+{
+}
+```
+
+The generator automatically includes the mapped derived types, so they don't need separate `[TomlSerializable]` roots.
+If the base type already has [`TomlDerivedTypeAttribute`](xref:Tomlyn.Serialization.TomlDerivedTypeAttribute) or [`JsonDerivedTypeAttribute`](xref:System.Text.Json.Serialization.JsonDerivedTypeAttribute) registrations, those take precedence over context-level mappings.
+
 ## Use generated metadata
 
 Use the generated [`TomlTypeInfo<T>`](xref:Tomlyn.TomlTypeInfo`1) property directly (recommended):
@@ -108,6 +126,7 @@ The source generator supports these attributes at compile time:
 | [`JsonPropertyNameAttribute`](xref:System.Text.Json.Serialization.JsonPropertyNameAttribute) / [`TomlPropertyNameAttribute`](xref:Tomlyn.Serialization.TomlPropertyNameAttribute) | [`JsonConstructorAttribute`](xref:System.Text.Json.Serialization.JsonConstructorAttribute) / [`TomlConstructorAttribute`](xref:Tomlyn.Serialization.TomlConstructorAttribute) |
 | [`JsonIgnoreAttribute`](xref:System.Text.Json.Serialization.JsonIgnoreAttribute) / [`TomlIgnoreAttribute`](xref:Tomlyn.Serialization.TomlIgnoreAttribute) | [`JsonPolymorphicAttribute`](xref:System.Text.Json.Serialization.JsonPolymorphicAttribute) / [`TomlPolymorphicAttribute`](xref:Tomlyn.Serialization.TomlPolymorphicAttribute) |
 | [`JsonIncludeAttribute`](xref:System.Text.Json.Serialization.JsonIncludeAttribute) / [`TomlIncludeAttribute`](xref:Tomlyn.Serialization.TomlIncludeAttribute) | [`JsonDerivedTypeAttribute`](xref:System.Text.Json.Serialization.JsonDerivedTypeAttribute) / [`TomlDerivedTypeAttribute`](xref:Tomlyn.Serialization.TomlDerivedTypeAttribute) |
+|  | [`TomlDerivedTypeMappingAttribute`](xref:Tomlyn.Serialization.TomlDerivedTypeMappingAttribute) |
 | [`JsonObjectCreationHandlingAttribute`](xref:System.Text.Json.Serialization.JsonObjectCreationHandlingAttribute) | [`JsonObjectCreationHandlingAttribute`](xref:System.Text.Json.Serialization.JsonObjectCreationHandlingAttribute) |
 | [`JsonPropertyOrderAttribute`](xref:System.Text.Json.Serialization.JsonPropertyOrderAttribute) / [`TomlPropertyOrderAttribute`](xref:Tomlyn.Serialization.TomlPropertyOrderAttribute) | |
 | [`JsonRequiredAttribute`](xref:System.Text.Json.Serialization.JsonRequiredAttribute) / [`TomlRequiredAttribute`](xref:Tomlyn.Serialization.TomlRequiredAttribute) | |