Implement BulkInsertWithVersionAsync — OverwriteIfVersionMatches semantics (#48)

[jeremydmiller]

Summary

Closes #48 — the final row in the jasperfx#218 dedup audit (database-manipulation slice) and the only piece of feature work the audit identified. Everything else under #218 was pure consolidation onto `Weasel.Core` / `JasperFx`.

Adds three overloads of `AdvancedOperations.BulkInsertWithVersionAsync`:

```csharp
public Task BulkInsertWithVersionAsync(
IReadOnlyCollection<(T Document, long ExpectedVersion)> documents,
CancellationToken token = default);

public Task BulkInsertWithVersionAsync(
IReadOnlyCollection<(T Document, long ExpectedVersion)> documents,
int batchSize,
CancellationToken token = default);

public Task BulkInsertWithVersionAsync(
IReadOnlyCollection<(T Document, long ExpectedVersion)> documents,
int batchSize,
string tenantId,
CancellationToken token = default);
```

The shape mirrors the existing `BulkInsertAsync` overload set, with `(T, long)` pairs in place of bare `T` for the input collection.

Design decisions

Per the three open questions in #48's body:

1. API surface — sibling method, not convention-discovered. A separate `BulkInsertWithVersionAsync` rather than introducing a version-property convention on `T`. Less coupling, no Polecat-side metadata-discovery mechanism required. The audit body's first option.

2. SQL — version-guarded MERGE with `OUTPUT inserted.id`. Per-row MERGE statements concatenated into the batched command (matches the existing OverwriteExisting batching). Each MERGE has `OUTPUT inserted.id` so the reader can later determine which incoming rows the MERGE actually touched. Each output is its own result set; the reader iterates with `NextResultAsync`.

3. Failure semantics — per-row `JasperFx.ConcurrencyException`. When an incoming id is absent from the collected output set, the WHEN MATCHED AND ... predicate failed (the row exists at a different version than expected). After the batch's reader drains, the first missing id surfaces `new ConcurrencyException(typeof(T), id)`. Matches `UpdateOperation` / `UpsertOperation`. Audit body's second option.

Stop-sign in the docs

The throw is best-effort, not transactional. Matched-and-updated rows in the batch commit before the throw fires. One of the tests (`mixed_batch_partial_success_throws_on_first_mismatch`) pins this behavior so callers know what to expect. If transactional semantics are wanted later, that's a follow-up — likely involves wrapping the batch in an explicit `BEGIN TRAN` / `ROLLBACK` on mismatch detection.

Other changes

• The versionless `BulkInsertAsync` overload no longer throws `NotSupportedException` for `BulkInsertMode.OverwriteIfVersionMatches`. With Implement BulkInsertMode.OverwriteIfVersionMatches #48 implemented, the error message now points callers at the new `BulkInsertWithVersionAsync` sibling instead of citing Implement BulkInsertMode.OverwriteIfVersionMatches #48 as the blocker.

Test plan

• `dotnet build polecat.slnx -c Debug` — clean
• Integration tests run on CI (require SQL Server):
  • `missing_id_is_inserted` — fresh row, NOT MATCHED branch
  • `matching_version_updates_and_bumps_version` — happy path
  • `mismatched_version_throws_concurrency_exception` — original row untouched after throw
  • `mixed_batch_partial_success_throws_on_first_mismatch` — pins best-effort semantics
  • `versionless_overload_with_version_mode_throws_helpful_invalidoperation` — message pins
  • `empty_collection_does_nothing` — guard

Audit closure

This is the last open row across all three dedup audit slices. On merge:

• jasperfx#218 (database-manipulation) — fully complete.
• jasperfx#219 (events / projections) — already complete.
• jasperfx#224 (multi-tenancy) — already complete.

🤖 Generated with Claude Code