[Next] Strengthen public API governance, nullability and regression protection

[rodri-oliveira-dev]

Pain / problem

FluentMap 3.x now exposes a substantially larger public surface across core mapping, isolated runtimes, DI, analyzers, generators, streaming, multi-mapping and generated materialization.

The repository already has package validation, tests, Sonar, CodeQL and BenchmarkDotNet, but several long-term maintenance protections are still missing:

• public API changes are not reviewed against an explicit checked-in API snapshot;
• nullable reference type annotations are not enabled consistently on the public libraries;
• compatibility validation is focused on the currently supported/pinned dependency matrix and does not provide early warning for upcoming dependency changes;
• benchmarks exist but performance drift is not tracked as a first-class regression signal.

Goal

Make public API evolution, nullability, forward-compatibility signals and performance regressions explicit and reviewable without introducing flaky required gates.

Branch and delivery workflow

This is the final implementation workstream of roadmap #216 and continues on the shared branch roadmap/216-next-3x.

• Do not create a new implementation branch.
• Start from the existing roadmap/216-next-3x containing the completed [Next] Stabilize compatibility metadata and repository consistency #212, [Next] Expand strict generated materialization and Native AOT coverage #213 and [Next] Complete advanced mapping capabilities without expanding ORM scope #214 work.
• Preserve and validate all previous roadmap changes while implementing [Next] Strengthen public API governance, nullability and regression protection #215.
• After [Next] Strengthen public API governance, nullability and regression protection #215 and the full roadmap validation are complete, push the final branch state.
• This is the only child issue that opens a pull request.
• Open one pull request from roadmap/216-next-3x to main containing the complete [Next] Stabilize compatibility metadata and repository consistency #212–[Next] Strengthen public API governance, nullability and regression protection #215 roadmap implementation.
• The PR must reference roadmap [Roadmap] FluentMap 3.x: generated/AOT maturity, mapping completeness and API governance #216 and use closing references for [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.
• Before opening the PR, review the complete cumulative diff against main, not only the files changed by [Next] Strengthen public API governance, nullability and regression protection #215.

Scope / implementation requirements

1. Add explicit public API governance

Introduce checked-in public API baselines for every shipped library package.

A PublicAPI.Shipped.txt / PublicAPI.Unshipped.txt model using Roslyn PublicApiAnalyzers is acceptable and preferred when it fits the existing analyzer/tooling stack. An equivalent deterministic API-snapshot mechanism is acceptable if it provides the same review guarantees.

Cover at least:

• Dapper.FluentMap;
• Dapper.FluentMap.Dommel;
• FluentMap.DependencyInjection;
• public analyzer/generator package API where applicable.

CI must fail when a public API changes without an intentional baseline update.

Package validation remains enabled; API snapshots complement it rather than replace it.

2. Enable and correct nullable reference type annotations

Enable nullable analysis for maintained source projects in a controlled way.

Requirements:

• public contracts must accurately distinguish nullable from non-nullable values;
• avoid widespread ! suppression as a substitute for modeling the contract;
• preserve binary compatibility;
• avoid unnecessary source-breaking annotation changes where the API cannot safely make a stronger promise;
• annotate asynchronous/streaming/multi-mapping null-child scenarios consistently;
• update XML documentation where null behavior is part of the contract.

If enabling nullable globally reveals too much debt for one safe change, introduce project-level staged enforcement, but the final public shipped API must have a deliberate nullable contract.

3. Add compatibility canary workflows

Add scheduled/manual non-release compatibility canaries for dependencies/providers where early warning is useful.

At minimum, cover:

• the supported Dapper minimum;
• current latest stable Dapper;
• a clearly labeled forward-looking Dapper lane when a newer stable/prerelease can be resolved;
• provider client updates that can be tested without changing the supported matrix.

Canary failures must not silently redefine support. They are early-warning evidence only.

Keep the supported/certified matrix in COMPATIBILITY.md distinct from canary experiments.

4. Add performance regression reporting

Use the existing BenchmarkDotNet project to establish repeatable baselines for materialization hot paths, including where applicable:

• historical root-level type mapping;
• runtime QueryMapped* materialization;
• generated materialization;
• multi-mapping;
• converter-enabled materialization.

Add a scheduled/manual comparison workflow that records machine-readable benchmark output and highlights material regressions.

Do not make noisy hosted-runner microbenchmarks a required PR gate unless repeatability has been demonstrated. The initial implementation may be report-only with explicit thresholds and artifacts; any hard-fail threshold must be justified by measured variance.

5. Document the governance model

Document how maintainers intentionally:

• add/change public APIs;
• update shipped/unshipped API snapshots;
• interpret nullable annotations;
• interpret canary failures;
• evaluate benchmark regressions.

Out of scope

• Changing the minimum target framework solely to enable nullable reference types.
• Treating prerelease dependency canaries as supported versions.
• Replacing package compatibility validation.
• Failing normal PRs on unstable/noisy benchmarks.
• Large public API redesigns unrelated to annotations/governance.

Definition of Ready (DoR)

• Current package validation is green.
• Current public package set is known and matches the package catalog.
• Current compiler/language versions can support the selected nullable/API analyzer approach without changing consumer TFMs.
• Existing BenchmarkDotNet scenarios run successfully and produce machine-readable output.
• Current CI has a suitable scheduled/manual workflow pattern for canary and benchmark jobs.

Acceptance criteria

Public API

• Every shipped library has an explicit checked-in API baseline or equivalent.
• An unapproved public API change causes CI validation to fail.
• An intentional additive API change has a documented update path.

Nullability

• Maintained public projects compile under the selected nullable enforcement level.
• Public nullable annotations match actual behavior for representative mapping/query APIs.
• No large set of blanket suppressions is introduced.

Compatibility canary

• Scheduled/manual canary execution is separate from the supported release matrix.
• Canary output clearly identifies supported vs experimental dependency versions.
• Canary failure does not change package support claims automatically.

Performance

• Benchmark results are emitted in a machine-readable artifact.
• Current-vs-baseline comparison identifies material changes.
• Thresholds/reporting behavior are documented and calibrated to observed variance.

Definition of Done (DoD)

• The complete [Next] Stabilize compatibility metadata and repository consistency #212–[Next] Strengthen public API governance, nullability and regression protection #215 implementation is committed and pushed to roadmap/216-next-3x.
• One final pull request is opened from roadmap/216-next-3x to main, references [Roadmap] FluentMap 3.x: generated/AOT maturity, mapping completeness and API governance #216 and closes [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 on merge.
• The PR description summarizes the cumulative roadmap implementation and validation evidence rather than only [Next] Strengthen public API governance, nullability and regression protection #215.
• API governance is enforced in CI.
• Nullable contracts are enabled and documented for maintained public libraries without an intentional binary break.
• Compatibility canary workflow runs successfully and produces actionable output.
• Benchmark regression workflow/reporting runs successfully and preserves historical results/artifacts as configured.
• Maintainer documentation explains the required update process for API baselines, nullability, canaries and benchmarks.
• Existing provider, generator, analyzer, Native AOT, pack, Sonar and CodeQL checks remain green.
• COMPATIBILITY.md continues to distinguish certified support from experimental/canary evidence.
• Changelog records any consumer-visible annotation or API-governance change.