[Roadmap] FluentMap 3.x: generated/AOT maturity, mapping completeness and API governance

[rodri-oliveira-dev]

Pain / problem

The previous 3.x roadmap established the current foundation: mainline/release stabilization, real-provider certification, two-type multi-mapping, asynchronous mapped multiple results, strict generated materialization, reordered generated shapes, Native AOT evidence and MySQL/MariaDB certification.

The repository is now mature enough that the next cycle should focus primarily on library capability and long-term API quality rather than another broad repository-cleanup effort.

Four gaps remain especially valuable:

1. compatibility metadata can still drift between package constraints, CI and documentation;
2. strict generated materialization/Native AOT support is useful but still intentionally narrow;
3. mapping functionality is incomplete around writes, higher-arity multi-mapping and explicit immutable/value-object construction;
4. the expanded 3.x public surface needs stronger API/nullability/compatibility/performance governance.

Outcome

Evolve FluentMap 3.x as a focused, compatibility-conscious mapping layer for Dapper with:

• one verifiable compatibility contract;
• a more practical generated-only/Native AOT path;
• more complete mapping capabilities without ORM scope creep;
• explicit public API and regression governance.

This roadmap does not assign release numbers in advance. Each workstream must preserve SemVer; release slicing is decided from the actual public API impact once implementation is ready.

Branch and pull-request strategy

All child issues in this roadmap are implemented sequentially on one shared branch:

roadmap/216-next-3x

Execution model:

1. [Next] Stabilize compatibility metadata and repository consistency #212 creates the shared branch from the current main, then commits and pushes its completed work.
2. [Next] Expand strict generated materialization and Native AOT coverage #213 continues on the same branch, commits and pushes, and does not open a PR.
3. [Next] Complete advanced mapping capabilities without expanding ORM scope #214 continues on the same branch, commits and pushes, and does not open a PR.
4. [Next] Strengthen public API governance, nullability and regression protection #215 continues on the same branch and performs the final cumulative validation.
5. Only after [Next] Strengthen public API governance, nullability and regression protection #215 is complete, open one pull request from roadmap/216-next-3x to main containing the entire roadmap implementation.
6. The final PR must reference [Roadmap] FluentMap 3.x: generated/AOT maturity, mapping completeness and API governance #216 and close [Next] Stabilize compatibility metadata and repository consistency #212, [Next] Expand strict generated materialization and Native AOT coverage #213, [Next] Complete advanced mapping capabilities without expanding ORM scope #214 and [Next] Strengthen public API governance, nullability and regression protection #215 when merged.

Do not create one branch or PR per child issue. Do not merge partial roadmap work into main.

Delivery plan

Order	Workstream	Issue	Primary outcome	Dependency
1	Stabilization and consistency	#212	One verified compatibility/package/CI/documentation contract	None
2	Generated materialization and Native AOT	#213	Practical parameterized strict-generated path and broader AOT evidence	#212 completed on the shared branch
3	Mapping capability completeness	#214	Write converters, 3+ type multi-mapping and explicit construction strategy	#213 completed on the shared branch
4	API and engineering maturity	#215	Public API snapshots, nullability, canaries and performance regression reporting	#214 completed on the shared branch; opens the single final PR

Workstreams

#212 — Stabilize compatibility metadata and repository consistency

Required result:

• reconcile the Dapper minimum dependency drift;
• enforce consistency across package metadata, CI and documentation;
• resolve the inherited-property reflection/mapping TODO with an explicit tested contract;
• prevent the same class of drift from recurring.

This issue is the first delivery gate because subsequent work should not build on an ambiguous package compatibility baseline.

#213 — Expand strict generated materialization and Native AOT coverage

Required result:

• support a practical parameterized strict-generated query path without hidden reflection fallback;
• broaden safe reader shapes where unambiguous;
• keep strict diagnostics deterministic;
• expand Native AOT smoke evidence;
• preserve runtime/generated equivalence.

This workstream improves the existing generated/AOT architecture rather than creating a parallel query framework.

#214 — Complete advanced mapping capabilities without expanding ORM scope

Required result:

• execute configured write converters through supported Dommel writes;
• extend FluentMap-controlled multi-mapping beyond two input types;
• introduce an explicit immutable/value-object construction strategy;
• keep all behavior inside mapping/materialization boundaries.

This workstream must not introduce generic CRUD generation, SQL parsing, query building, change tracking or automatic graph aggregation.

#215 — Strengthen public API governance, nullability and regression protection

Required result:

• checked-in public API baselines;
• deliberate nullable-reference-type contracts;
• forward-looking compatibility canaries that do not redefine support;
• repeatable performance regression reporting using the existing benchmark project.

The final API baseline for this roadmap should include intentional public APIs added by preceding workstreams.

Dependency and sequencing rules

• Execute the child issues sequentially: [Next] Stabilize compatibility metadata and repository consistency #212 → [Next] Expand strict generated materialization and Native AOT coverage #213 → [Next] Complete advanced mapping capabilities without expanding ORM scope #214 → [Next] Strengthen public API governance, nullability and regression protection #215.
• Every child issue uses the same shared branch roadmap/216-next-3x.
• [Next] Stabilize compatibility metadata and repository consistency #212–[Next] Complete advanced mapping capabilities without expanding ORM scope #214 must not open pull requests or merge partial work to main.
• If [Next] Complete advanced mapping capabilities without expanding ORM scope #214 adds generated-materialization behavior, it must use the strict/generated contracts established by [Next] Expand strict generated materialization and Native AOT coverage #213 rather than introducing a second mechanism.
• [Next] Strengthen public API governance, nullability and regression protection #215 performs final cumulative validation and opens the single roadmap pull request to main.
• A child workstream is considered implementation-complete when its own DoD is satisfied and its changes are committed/pushed to the shared branch; roadmap completion still requires the final PR to merge and post-merge evidence to pass.

Common implementation constraints

• Keep FluentMap a mapping/materialization layer for Dapper.
• Preserve the historical EntityMap<T>, FluentMapper.Initialize(...) and normal Dapper type-map path.
• Preserve documented global-state boundaries for normal Dapper queries and Dommel.
• Keep isolated FluentMapRuntime behavior explicit.
• Do not silently introduce reflection/dynamic-code fallback into strict-generated APIs.
• New public APIs must be SemVer-safe, documented and covered by negative/edge-case tests.
• Provider, performance, trimming/AOT and compatibility claims must be backed by reproducible evidence.
• Prefer internal reusable pipelines over overload-by-overload duplication.
• Do not add generic CRUD generation, LINQ translation, SQL parsing, query building, change tracking, Unit of Work, migrations or automatic one-to-many graph aggregation.

Definition of Ready (DoR)

The roadmap is ready to execute when:

• Current main CI is green or any unrelated failure is documented.
• [Next] Stabilize compatibility metadata and repository consistency #212–[Next] Strengthen public API governance, nullability and regression protection #215 each contain explicit scope, DoR, acceptance criteria, DoD and out-of-scope boundaries.
• The current supported Dapper/provider/AOT contract is documented in COMPATIBILITY.md.
• Existing generated/runtime/provider/benchmark test infrastructure is available as the baseline evidence set.
• No unresolved release-blocking issue from the previous roadmap is being silently carried into this roadmap.

Roadmap acceptance criteria

• [Next] Stabilize compatibility metadata and repository consistency #212 establishes and enforces one compatibility contract.
• [Next] Expand strict generated materialization and Native AOT coverage #213 makes strict generated materialization useful for at least one real parameterized query under Native AOT evidence.
• [Next] Complete advanced mapping capabilities without expanding ORM scope #214 closes the defined write-converter, higher-arity multi-mapping and explicit-construction gaps without ORM scope expansion.
• [Next] Strengthen public API governance, nullability and regression protection #215 makes public API changes, nullability, forward compatibility and benchmark drift explicitly reviewable.
• Documentation distinguishes supported/certified behavior from experimental/canary evidence.
• No workstream weakens existing required CI/provider/security/release checks to make its implementation pass.

Roadmap Definition of Done (DoD)

• [Next] Stabilize compatibility metadata and repository consistency #212–[Next] Strengthen public API governance, nullability and regression protection #215 have each satisfied their own DoD.
• All required work is merged to main.
• Mainline CI, provider compatibility, generator/analyzer tests, Native AOT smoke, pack validation, Sonar and CodeQL are green.
• Public API/package compatibility validation shows no undocumented breaking change.
• Supported dependency/provider/AOT claims match reproducible CI evidence.
• Public API baselines include the final intentional API surface delivered by this roadmap.
• Benchmark reporting has a documented baseline for the materialization paths changed by this roadmap.
• README/usage/migration/compatibility/changelog documentation is reconciled with actual shipped behavior.
• Release version(s) are selected according to SemVer from the implemented public API impact rather than from the roadmap labels.
• No roadmap checkbox is marked complete solely from implementation intent; completion is backed by tests and mainline evidence.

How to verify completion

Review the single final roadmap PR, each child issue's DoD evidence, the final main workflow runs, package validation output, provider matrix, Native AOT smoke, public API baseline changes and benchmark artifacts.

The final support claims must match what those artifacts demonstrate, not what the roadmap originally intended.