refactor(sequenceCache): implement explicit CacheState state machine

[kingsrichie79-cmyk]

Closes #701

Description

This PR refactors the sequence number cache in src/sequenceCache.ts to use an explicit state machine, replacing the previous implicit flag-based logic. This makes transitions between states fully auditable, strict, and easier to trace, preventing edge cases where the cache could end up in an invalid state.

Technical Changes

• Introduced CacheState Type Union: Defined CacheState as 'valid' | 'invalidated' | 'refreshing', completely replacing the scattered implicit tracking.
• Encapsulated State in SequenceEntry: Converted SequenceEntry from a basic interface into a class that holds and manages its own internal _state.
• Strict State Transitions: Added a single transition(newState: CacheState) method in SequenceEntry to funnel all state changes through a unified validation check.
• Custom Error Handling: Added a new StateTransitionError class. If an invalid transition is attempted (e.g., trying to transition from valid directly to refreshing without going through invalidated), it throws this error immediately.
• Preserved Public API: The existing public API (getSequence, invalidate, refresh) was left intact and is fully backward-compatible. Under the hood, they now trigger the correct transitions (e.g., invalidate() gracefully transitions from valid -> invalidated -> refreshing).

Acceptance Criteria Met

• A CacheState type union replaces the implicit boolean flags.
• All state transitions go through a single transition(newState) function that validates the transition.
• Invalid transitions throw a StateTransitionError.
• Unit tests pass.
• The public API (getSequence, invalidate, refresh) remains unchanged.

[drips-wave]

@kingsrichie79-cmyk Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits