feat(route): optimistic concurrency control for route updates (#549)

[Simultech369]

Summary

Closes #549

Implements Optimistic Concurrency Control (OCC) for all route updates across the StableRoute backend to eliminate race conditions and prevent lost updates under concurrency.

Key Changes

1. Store-Layer Atomic Compare-and-Set:

   • Added monotonic version: number to PairMeta model (defaults to 1).
   • Implemented updatePairMetaCas(key, expectedVersion, updater) in src/stores.ts ensuring atomic verification, mutation, and version increment at the store layer.
   • Added metaCas(key, expectedVersion, update) to the StorageAdapter interface, implemented for both InMemoryAdapter and JsonFileAdapter.
   • Updated persistence migration (migrateV0ToV1) and snapshot hydration to backfill version = 1 for legacy records.

2. HTTP Route Updates & Reads:

   • Enforced required expected version on all route updates (PATCH /fee_bps, /min, /max, /liquidity, /rate, /enabled, and POST /reset).
   • Supports version ingestion via request body (version, expected_version) and HTTP If-Match headers ("1", W/"1").
   • Rejects missing, blank, null, negative, or non-integer versions with 400 invalid_request.
   • Rejects version mismatches with 409 version_conflict, returning fresh currentVersion and expectedVersion so callers can safely re-fetch and retry.
   • Read routes (GET /api/v1/pairs/:source/:destination/info and GET /api/v1/pairs/:source/:destination) return version and emit matching ETag: "<version>" headers.

3. Documentation:

   • Updated src/openapi.ts with required version schemas and 409 responses.
   • Added docs/optimistic-concurrency-control.md detailing the OCC model, error taxonomy, and client retry patterns.
   • Updated docs/stores.md with PairMeta.version.

4. Testing & Edge Cases Covered:

   • Added dedicated test suite src/__tests__/occRouteUpdates.test.ts (28 tests):
     1. Two updates from same base version -> second gets 409 version_conflict with fresh currentVersion.
     2. Sequential updates each bumping version -> all succeed (v1 -> v2 -> v3 -> v4).
     3. Update with missing / blank / null / negative / float / string version -> 400 invalid_request.
     4. Update with future version -> 409 version_conflict with fresh currentVersion.
     5. Read always exposes current version (via GET /info and GET /:source/:destination).
     6. Concurrent races: Promise.all competing updates -> exactly 1 succeeds, others receive 409.
     7. Conditional If-Match header handling.
     8. Store-layer updatePairMetaCas and StorageAdapter.metaCas unit tests.
   • All 36 test suites pass (1,013 tests total, 0 regressions).
   • npm run lint passes with 0 errors.
   • npm run build compiles cleanly with 0 errors.