Add advanced mapping contracts for 1.2.0

[skuirrels]

Summary

• add explicit collection update policies, invocation-local reference preservation, and closed-world runtime dispatch
• add cached provider-neutral expression projections through the optional DomainMapper.Projections package
• make generator invalidation mapper-scoped and cover concurrency, trimming, native AOT, packaged consumers, and Roslyn compatibility
• document the 1.2.0 capabilities, diagnostics, compatibility policy, performance evidence, and stable release metadata
• harden reference tracking, projection eligibility, registry ambiguity, deferred-helper failures, and incremental invalidation found during review

Impact

DomainMapper 1.2.0 adds reusable opt-in advanced mapping contracts without assembly scanning, runtime reflection, persistence assumptions, or mutable runtime configuration. Convention-only consumers retain the existing direct generated-code path.

Validation

• Release build with warnings as errors: 0 warnings, 0 errors
• 120/120 unit and generator regression tests
• CSharpier, dotnet style/analyzer formatting, documentation lint/build, and git diff --check
• exact 1.2.0 package build across Roslyn 4.8, 4.11, 4.14, and 5.0
• clean packaged consumers on .NET 8, .NET 9, .NET 10, and .NET Framework 4.8
• packaged native AOT publish and runtime smoke
• tracking benchmark: 26.044 ns and 272 B versus the matched handwritten 26.475 ns and 272 B baseline
• cold generation median: 256.482 us and 501.2 KB, 1.208x the 212.3 us baseline and within the 1.25x gate

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'SourceGeneratorBenchmarks'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.25.

Benchmark suite	Current: 91d6eb6	Previous: a73afe7	Ratio
DomainMapper.Benchmarks.SourceGeneratorBenchmarks.DomainMapperColdGeneration	647115.8317708333 ns (± 2849.4856639081804)	424152.4607872596 ns (± 3926.4595598279025)	1.53

This comment was automatically generated by workflow using github-action-benchmark.

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'ComparisonMappingBenchmarks'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.25.

Benchmark suite	Current: 91d6eb6	Previous: e53a7e8	Ratio
DomainMapper.Benchmarks.ComparisonMappingBenchmarks.MapperlyValueObjectFactory	16.57613788980704 ns (± 0.9234156103640093)	6.188103819886844 ns (± 0.13244699807809548)	2.68

This comment was automatically generated by workflow using github-action-benchmark.