CBDD/docs/features/source-generated-mapping.md

Source-Generated Mapping

Purpose And Business Outcome

Generate compile-time mapping code to reduce runtime overhead and reflection risk for serialization paths.

Scope And Non-Goals

Scope:

• Entity metadata analysis
• Mapper source generation
• Collection initialization helpers

Non-goals:

• Runtime dynamic mapping for unknown schemas
• Support for unsupported C# patterns outside generator design

User And System Workflows

1. Consumer defines entities and context patterns.
2. Build invokes source generator.
3. Generated mapper code is compiled into target project.
4. Runtime serialization path uses generated code.

Interfaces And APIs

• Source generator project under src/CBDD.SourceGenerators
• Attributes in BSON and data-annotation mapping surface
• Generated initialization methods for context collections

Permissions And Data Handling

• Generated code can expose field-level mapping behavior.
• Repository write permissions should be limited to trusted contributors.

Dependencies And Failure Modes

Dependencies:

• Roslyn source generator execution during build
• Entity schema conventions

Failure modes:

• Missing generation due to invalid entity declarations
• Serialization mismatch caused by attribute/model changes

Monitoring, Alerts, And Troubleshooting

• Monitor build output for generator diagnostics.
• Use ../runbook.md for escalation.
• Follow ../security.md for review and control expectations.
• Use ../troubleshooting.md for remediation steps.

Rollout And Change Considerations

• Generator behavioral changes require broad regression tests across entities.
• Document any new constraints or unsupported patterns in release notes.

Validation Guidance

• Run source generator and serialization tests in tests/CBDD.Tests.
• Validate mapper generation with clean dotnet build in CI.