Enforce OTP domain invariants and safe restoration

[Amir-Golmoradi]

Summary

Strengthen PayGuard Identity's OTP Domain by enforcing lifecycle invariants, correcting nullness contracts, and ensuring safe restoration of previously persisted OTP challenges.

This PR focuses exclusively on domain correctness, state consistency, and regression testing.

Changes

OTP Aggregate

• Separate OTP issuance from historical state restoration.
• Restrict OTP.issue() to newly issued ACTIVE challenges with zero attempts.
• Allow OTP.restore() to reconstruct valid historical states without resetting attempts, identities, or timestamps.
• Preserve single-use verification semantics.
• Maintain atomic state transitions for successful and failed verification attempts.

OTP Snapshot

• Enforce the relationship between USED status and consumedAt.
• Validate consumption timestamps within the challenge validity period.
• Reject invalid attempt counts and lifecycle states.
• Correct handling of optional fields in snapshot construction and restoration.
• Preserve JSpecify nullness contracts with @NullMarked and @Nullable.
• Prevent invalid intermediate states during snapshot transitions.

Verification Policy

• Reject verification attempts with invalid timestamps.
• Enforce expiration boundaries.
• Preserve verification rejection precedence.
• Ensure rejected operations do not accidentally consume verification attempts.
• Preserve aggregate state when verification fails unexpectedly.

Domain Tests

• Cover issuance and historical restoration.
• Verify ACTIVE, USED, LOCKED, EXPIRED, and INVALIDATED states.
• Test successful verification and replay prevention.
• Test failed-attempt counting and lockout behavior.
• Verify expiration and consumption-time boundaries.
• Verify snapshot immutability and exception safety.

Verification

• OTP Domain unit tests pass.
• Snapshot invariant tests pass.
• Restoration scenarios are verified.
• JSpecify contracts are validated.
• Security review findings from Issue fix(verification): Enforce OTP domain invariants, nullness contracts, and safe restoration #25 are resolved or explicitly tracked.
• Maven build and relevant checks pass.

Related Issue

Closes #25