M2: execution core (SqlSession, SqlParameters)

[lgamorim]

What

Milestone 2 (Phase 1 — Bedrock) of the SqlBound roadmap: the hand-written runtime primitives that both manual callers and the future source generator (M4+) will call into.

• SqlParameters: an immutable, public, named parameter set. Normalizes null values to DBNull.Value at construction so downstream ADO.NET binding never needs a separate null check; rejects empty/whitespace/duplicate names.
• SqlSession: the coexistence-safe, instance-based entry point for the "dynamic surface" (deliberately not named Query*/Execute*/ExecuteScalar* on DbConnection, per the Dapper-coexistence design constraint). Never opens, closes, or owns the connection — requires an already-open one, fails fast with InvalidOperationException otherwise.
  • RunAsync: non-query execution, returns affected row count.
  • FetchScalarAsync<T>: scalar execution with DBNull/null-aware conversion to T (throws for non-nullable value types, default for nullable ones), falling back to Convert.ChangeType for same-family type mismatches (e.g. a provider returning long where int was requested).
  • Cancellation is checked before any ADO.NET call is made, and threaded through to the underlying async calls for mid-execution cancellation too.
• Hand-rolled ADO.NET test doubles (FakeDbConnection/FakeDbCommand/FakeDbParameter(Collection)) in the test project, chosen over a real provider to keep unit tests hermetic — the real-provider question is deferred to M3, which needs one regardless for the Dapper-coexistence sample.

Two infrastructure fixes surfaced along the way and landed as their own commits, ahead of the feature work that exposed them:

• .gitattributes: .editorconfig already declared end_of_line = lf, but nothing enforced it at the git layer — on Windows with core.autocrlf=true (a common default), every fresh checkout converted committed LF to CRLF, failing dotnet format on every file. Now normalized at the git level.
• Async-suffix naming rule exemption for tests: the M1 .editorconfig naming rule requiring an Async suffix on async methods didn't account for testing.md's Should_ExpectedOutcome_When_Scenario convention, which async test methods must also follow. Scoped off for test/**/*.cs.

Also upgraded the test project from the legacy xunit 2.x package to xunit.v3, keeping VSTest execution (Microsoft.NET.Test.Sdk + xunit.runner.visualstudio) so dotnet test and CI are unaffected.

Why

These are the primitives every later milestone builds on — M4's source generator will emit calls into SqlSession, and SqlParameters is public specifically because generated code compiles into the consumer's assembly.

Test plan

• Full TDD cycle (red → green → refactor) for every unit: SqlParameters, SqlSession.RunAsync, SqlSession.FetchScalarAsync<T>
• 31/31 tests passing locally
• dotnet build — 0 warnings, 0 errors (TreatWarningsAsErrors + EnforceCodeStyleInBuild)
• dotnet format --verify-no-changes — clean
• dotnet pack — succeeds
• CI green on this PR (first real execution of the xunit.v3 + .gitattributes changes on a Linux runner)

Reviewer notes

• SqlSession requiring an already-open connection (no auto-open/close) is deliberate, not an oversight — see the Dapper-coexistence constraint in CLAUDE.md.
• ConvertScalar<T>'s default(T) is not null check is the standard idiom for "is T a non-nullable value type" at runtime; used to decide throw-vs-return-default for a null/DBNull scalar result.

🤖 Generated with Claude Code