optimistic concurrency control for route updates

[mikewheeleer]

Summary

Concurrent updates to the same route silently clobber each other (last-write-wins). Add a version field and reject stale writes so lost updates become impossible.

Why this matters

Lost updates corrupt route state under concurrency. OCC is the standard, lock-free fix and makes conflicts explicit to clients.

Requirements

• Add a monotonic version to the route model, returned on every read.
• Require the client's expected version on update; bump it atomically on success.
• Reject a mismatched version with 409 version_conflict including the current version.
• All existing update paths go through the guarded write.

Technical guidance

• Do the compare-and-set atomically at the store layer, not in the handler.
• Return the fresh version in both success and conflict responses so clients can retry.

Edge cases — each must have a test

• two updates from the same base version -> second gets 409
• sequential updates each bumping version -> both succeed
• update with a missing/blank version -> 400
• update with a future version -> 409
• read always exposes the current version

Acceptance criteria

• All requirements and every edge case above implemented and covered by tests
• New unit and integration tests; existing tests still pass and no regressions
• Structured, typed errors (no leaked internals; stable codes)
• npm run lint, npm test, and npm run build all pass locally
• Code follows the repo's existing conventions; no duplication or dead code
• Short docs/comments explaining the design and any non-obvious decisions
• PR description explains the approach and includes Closes #<issue>

Out of scope

• Field-level/merge conflict resolution
• Historical version audit trail

Rewards

Part of the GrantFox OSS / Official Campaign (FWC26) — this task may be rewarded. PR quality is assessed by AI: depth, correctness under edge cases, meaningful tests, and clean design are what earn the reward. Shallow changes (typos, formatting, trivial docs) do not qualify.