Follow-up: thread-safety and robustness hardening in stat aggregation

[mjfelis]

Context

Follow-up to #16, which addressed the highest-priority concurrency fixes. This issue tracks the remaining hardening items that were intentionally deferred because they need a more careful design pass and review. These are robustness / tech-debt improvements, not user-facing feature work.

Kept intentionally high-level. Please discuss design before implementing.

Items

1. Persistence-context usage under concurrency

The aggregation and flush paths are exercised by multiple worker threads. We should review how the persistence context is obtained and ensure each unit of work uses an appropriately scoped context with clear transaction boundaries, rather than relying on a single shared instance. Goal: make the read/persist/merge paths robust under load.

2. Stable locking around flush

The per-bucket lock used to guard in-memory counter updates should remain stable for the full duration of a flush, so that concurrent updates and the flush are always mutually exclusive. Review the lock lifecycle so a lock is not retired while updates for the same bucket may still occur.

3. Consistent locking for on-demand flush

The query-triggered flush path should use the same per-bucket locking discipline as the periodic flush, so both paths are consistent.

4. Defensive handling of concurrently-removed buckets

The periodic flush should tolerate a bucket being removed concurrently (skip gracefully) instead of relying on a broad catch-all.

5. Request validation ordering on the query API

Validate required request fields before deriving values from them, so malformed requests return 400 Bad Request instead of a 500.

Notes

• Suggested approach: tackle as small, independently reviewable PRs (1–2 items each), with a focused test for each.
• Performance side-effects (e.g. lock granularity, reflection on the hot path) can be considered alongside merge back to dev #1/Dev #2 but are not required here.

[mjfelis]

PR #18 addresses 4 of the 5 items:

• Item 2 — stable locking around flush (periodic flush now holds the per-bucket lock across flush + cache replacement)
• Item 3 — consistent locking for on-demand flush (same statLockObj → dateStats ordering as the periodic flush)
• Item 4 — defensive handling of concurrently-removed buckets
• Item 5 — request validation ordering on the query API
• Item 1 — persistence-context / transaction boundaries: still open. Deferred for a separate, test-backed change since it can alter commit semantics and needs a DB-backed test to validate safely.

Leaving this issue open to track item 1.