feat: Complete CM-5 BookState interface implementation

[callummiles]

feat: Complete CM-5 BookState interface implementation

Summary

Completes the BookState interface implementation work for Jira ticket CM-5 by fixing a critical runtime blocker, adding comprehensive documentation, and creating a full test suite for the new_model/ state pattern implementation.

Key Changes:

• ✅ Critical Fix: Added missing Version.next() method that was causing runtime failures in Book.java
• ✅ Documentation: Added comprehensive JavaDoc to BookState interface and all state implementations (AvailableState, OnHoldState, CheckedOutState, Book)
• ✅ Test Suite: Created 5 Groovy/Spock test files with 59 tests covering state transitions, validation, and business rules
• ✅ Build Fix: Removed **/new_model/** exclusion from pom.xml and fixed incorrect package declarations in BookRepository and BookDuplicateHoldFound

Test Results: All 148 tests passing (89 existing + 59 new)

Review & Testing Checklist for Human

• Version.next() implementation - Verify the method is correct and consistently used across all state transitions in Book.java
• State transition logic - Review OnHoldState.checkout() to ensure it correctly validates that only the patron who placed the hold can check out the book
• Package declarations - Confirm BookRepository and BookDuplicateHoldFound are now in the correct new_model package (were incorrectly in model package)
• Manual testing - Test the state transitions end-to-end: Available → OnHold → CheckedOut → Available, and verify version increments correctly at each step
• Edge cases - Review test coverage for edge cases like expired holds, invalid patron checkouts, and concurrent state changes

Recommended Test Plan:

1. Create a book in Available state
2. Place hold as Patron A, verify state = ON_HOLD, version = 1
3. Try checkout as Patron B (should fail), verify state still ON_HOLD
4. Checkout as Patron A (should succeed), verify state = CHECKED_OUT, version = 2
5. Return book, verify state = AVAILABLE, version = 3

Notes

• JavaDoc Build: The mvn javadoc:javadoc command shows errors, but these are all in the pre-existing ui/ package which is excluded from normal compilation. My new_model/ JavaDoc loaded successfully without errors.
• Architecture: This new_model/ implementation uses mutable State pattern with bidirectional references, as an alternative to the immutable type-based model/ package. Both packages now coexist in the codebase.
• Package Fix: BookRepository and BookDuplicateHoldFound were declaring themselves in the wrong package, causing duplicate class compilation errors. This has been corrected.

---

Link to Devin run: https://app.devin.ai/sessions/453e77fa348b43aca456fc4dee5b2df0
Requested by: Callum Miles (@callummiles)
Jira Ticket: CM-5

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring