fix: clarify queued repo lock lifecycle

[patrickleet]

Summary

• make manual QueuedRepository::lock fail when the lock is already held
• document locking read, drop, and commit-error lock lifecycle semantics
• add regression tests for manual lock failure and commit errors retaining locks until abort
• clarify that Postgres row/advisory locks replace process-local queue locks for cross-process coordination

Verification

• cargo test --test todos
• cargo fmt --check
• git diff --check
• cargo test --all-features

Note: all-features still reports the existing Reservation dead-code warning in tests/sagas/order/inventory.rs.

Summary by CodeRabbit

• Bug Fixes

  • Lock acquisition now properly reports an error when attempting to acquire an already-held lock.

• Documentation

  • Added documentation clarifying the locking model, concurrency enforcement, and lock lifetime semantics.

• Tests

  • Added concurrency tests verifying lock behavior and error handling during concurrent operations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 853b0335-4d77-4a08-b268-8efab0903972

📥 Commits

Reviewing files that changed from the base of the PR and between 21b93b9 and 93eebb1.

📒 Files selected for processing (3)

• docs/postgres-event-store.md
• src/queued_repo/repository.rs
• tests/todos/main.rs

---

📝 Walkthrough

Walkthrough

The PR refines QueuedRepository locking semantics by adding error reporting for failed lock acquisitions, documenting lock lifetime and intentional retention on commit errors, and verifying the behavior with two new concurrency tests covering lock acquisition failures and lock retention across optimistic write conflicts.

Changes

QueuedRepository Lock Semantics and Error Handling

Layer / File(s)	Summary
Locking model documentation docs/postgres-event-store.md	New "Locking Model" section clarifies that QueuedRepository is process-local only and must not serve as a durable cross-process mechanism; Postgres should use optimistic concurrency via uniqueness constraints and transaction-scoped row/advisory locks.
Lock acquisition and error reporting src/queued_repo/repository.rs	QueuedRepository::lock() now reports RepositoryError when lock acquisition fails; expanded comments document lock lifetime (retained after reads, released on successful commits, retained on failures) for single and batch commit paths.
Lock acquisition and retention tests tests/todos/main.rs	Two new tests verify lock behavior: manual_lock_reports_failure_when_already_held confirms acquisition failures are reported, and commit_failure_keeps_lock_until_abort verifies locks are retained during concurrent write conflicts until explicitly released.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Locks held tight on error's chance,
Queued repos dance their local dance,
Postgres guards what's truly shared,
With atomicity well prepared!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix: clarify queued repo lock lifecycle' directly and clearly summarizes the main change: clarifying the locking behavior and lifecycle semantics of QueuedRepository.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/queued-repo-lock-lifecycle

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}