[DRK-175] Atomic idempotency key reservation (PostgreSQL store)

[baoduy]

Problem

IdempotencyPostgresStore had the same non-atomic check-then-act race DRK-75 fixed in IdempotencySqlServerStore: IsKeyProcessedAsync was a pure read, and MarkKeyAsProcessedAsync only wrote afterward, so two concurrent requests with the same idempotency key could both execute the protected handler.

Fix

• IdempotencyPostgresStore.IsKeyProcessedAsync now atomically inserts a StatusCode=102 reservation placeholder (leveraging the existing UX_CompositeKey unique index) before returning "not processed" — only one concurrent caller per key proceeds to run the handler.
• IdempotencyKeyEntity gained an internal Complete(CachedResponse) mutator so MarkKeyAsProcessedAsync completes the reservation row in place instead of blind-inserting.
• IdempotencyOptions.InFlightReservationTimeout (default 30s) bounds how long a reservation is honoured before being treated as expired/abandoned.
• A reservation collision against an expired row is itself reclaimed atomically via a conditional ExecuteUpdateAsync (only one racer's update affects a row) — an intermediate build had a residual race here (an unconditional "proceed as new" let every racer through), closed during this cycle's QC pass.

Tests

• Tightened CreateItem_ConcurrentRequestsWithSameKey_OnlyOneProcessed to assert every concurrent Created response carries the identical item id (proves the handler ran once, not just that the DB has one row).
• New CreateItem_WithExpiredInFlightReservation_ProcessesAsNewRequest — an expired reservation doesn't permanently block retries.
• New CreateItem_ConcurrentRequestsAgainstExpiredReservation_OnlyOneProcessed — concurrent requests racing an expired reservation still execute the handler exactly once.
• AspCore.Idempotency.NpgsqlStore.Tests: 19/19, repeated across 5 full runs for determinism. AspCore.Idempotency.Tests: 57/57. Coverage on touched files ≥ 97.7%. Clean dotnet build and dotnet pack.

Scope

src/AspNet/DKNet.AspCore.Idempotency.NpgsqlStore/Store/IdempotencyPostgresStore.cs, .../Data/IdempotencyKeyEntity.cs, src/AspNet/DKNet.AspCore.Idempotency/IdempotencyOptions.cs, src/AspNet/AspCore.Idempotency.NpgsqlStore.Tests/Integration/IdempotencyIntegrationTests.cs — no other files touched.

Addresses finding IDEM-CONCURRENCY-001 (DRK-175).

[github-actions]

📊 Code Coverage Report

| Metric | Coverage |
|--------|----------|
| **Line Coverage** | 82.3% |
| **Branch Coverage** | 80.6% |
| **Method Coverage** | 84.4% |

**Lines:** 3455/undefined covered
**Branches:** 1292/undefined covered

📈 [View Full Coverage Report](https://github.com/baoduy/DKNet/actions/runs/30974921330)

[codecov]

Codecov Report

❌ Patch coverage is 80.88235% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.14%. Comparing base (4e9c6de) to head (f7438f3).

Files with missing lines	Patch %	Lines
...ency.NpgsqlStore/Store/IdempotencyPostgresStore.cs	79.03%	9 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##              dev     #341      +/-   ##
==========================================
+ Coverage   78.99%   79.14%   +0.15%     
==========================================
  Files         169      169              
  Lines        4142     4196      +54     
  Branches      608      613       +5     
==========================================
+ Hits         3272     3321      +49     
- Misses        689      694       +5     
  Partials      181      181              

Flag	Coverage Δ
unittests	79.14% <80.88%> (+0.15%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[baoduy]

PR Review: #341 — Atomic idempotency key reservation (PostgreSQL store)

Verdict: APPROVED (score 10.0/10) — merging into dev. Review vote skipped (self-authored PR; GitHub rejects self-approvals).

Score

Category	Score	Weight
Correctness & logic	10	25%
Security	10	20%
Testing & coverage	10	20%
Maintainability & design	10	15%
Spec conformance	10	10%
Style & conventions	9.5	5%
AI-slop gate	10	5%

Weighted: 9.975 → 10.0. No hard caps triggered.

Top findings

1. [praise] IdempotencyPostgresStore.cs:163–171 — The atomic ExecuteUpdateAsync reclaim elegantly solves the expired-row concurrency race without a schema change, using affected-row count for the same single-winner guarantee the unique index gives the fresh-insert path.
2. [praise] IdempotencyIntegrationTests.cs:75–93 — The tightened concurrency test now asserts all 201 responses carry the identical handler-generated Id, proving single-execution rather than the old lenient check.
3. [praise] IdempotencyKeyEntity.cs:111 — Complete() reuses the existing private-setter infrastructure rather than adding new public setters.
4. [nit] IdempotencyPostgresStore.cs:83 — DateTime.UtcNow vs DateTimeOffset? ExpiresAt type mismatch in the LINQ expression. Works correctly in EF Core; pre-existing pattern.
5. [suggestion] IdempotencyPostgresStore.cs:238 — The defensive catch block in MarkKeyAsProcessedAsync logs at Information level; consider Warning so unexpected triggering is observable.

Preconditions

• CI: 6/6 passed (build-test-coverage green)
• Coverage: ≥97.7% (QC-verified via [D175-2])
• Base: dev, not draft, no protected paths
• No secrets, no new dependencies, no scope creep

Out-of-scope

IdempotencySqlServerStore.cs:60–86 still uses the non-atomic check-then-act pattern — that's DRK-75's scope (parallel cycle), not introduced here.