feat(examples): demonstrate durable reservation idempotency

[yordis]

• Queue redelivery must converge on one durable operation outcome even when workers crash between inventory writes and acknowledgements.
• Competing retries need bounded deduplication without retaining every processed operation in inventory state.
• The guarantees around event identity and expected revision need to be explicit enough to prevent accidental duplicate reservations or releases.

[cursor]

PR Summary

Low Risk
Changes are limited to example code and dev-dependencies; no library or runtime behavior in trogon-eventstore is modified.

Overview
Replaces the idempotent_reservation example’s in-stream idempotency index with per-operation EventStore streams and a small state machine (requested → prepared/rejected → completed/conflicted).

Operation IDs are now deterministic from a job key (Uuid::new_v5), and inventory reserve/release is driven through claim_operation, optimistic inventory appends with revision checks, and terminal outcomes (complete, reject, or conflict) so queue redelivery and concurrent workers converge without duplicating inventory events or keeping every processed operation on the inventory aggregate.

The demo scenario is expanded: early claim before inventory read, crash between inventory commit and operation completion, racing competing reservations, persisted sold-out rejections, and stream timelines. examples/Cargo.toml adds serde_json and enables UUID v5.

^{Reviewed by Cursor Bugbot for commit fd8e3f7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 635beb6d-8c1f-48ef-89eb-33136ead82d3

📥 Commits

Reviewing files that changed from the base of the PR and between a473467 and fd8e3f7.

📒 Files selected for processing (2)

• examples/Cargo.toml
• examples/idempotent_reservation.rs

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Walkthrough

The example now uses deterministic UUID v5 operation IDs and per-operation event streams. It validates operation recovery, retries delivery, coordinates inventory writes, and demonstrates replay, conflicts, reservation races, and sold-out rejection.

Changes

Idempotent reservation state machine

Layer / File(s)	Summary
Operation contracts and state model examples/Cargo.toml, examples/idempotent_reservation.rs	Defines deterministic operation IDs, operation event payloads, operation states, inventory views, and stream result types.
Operation reading and claiming examples/idempotent_reservation.rs	Reads and validates operation streams, then claims new operations while detecting mismatched request content.
Inventory decision and terminalization examples/idempotent_reservation.rs	Prepares or rejects requests, appends inventory events, and records completed or conflicted outcomes.
Retries and recovery scenarios examples/idempotent_reservation.rs	Adds initial-stream creation, retry delivery, completed-write extraction, and scenarios for replay, races, conflicts, and sold-out inventory.

Priority: ⬇️ Low

Estimated code review effort: 4 (Complex) | ~60 minutes

Merge Risk: 🔵 Low · up to fd8e3

The new idempotent reservation example is mergeable with low risk, though it may fail to compile on older Rust configurations or fail a recovery assertion if position semantics differ.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant execute_operation
  participant OperationStream
  participant InventoryStream

  Client->>execute_operation: submit reservation operation
  execute_operation->>OperationStream: claim operation
  OperationStream-->>execute_operation: Requested state
  execute_operation->>OperationStream: append Prepared or Rejected
  execute_operation->>InventoryStream: append reservation event
  InventoryStream-->>execute_operation: committed write or conflict
  execute_operation->>OperationStream: append Completed or Conflicted
  execute_operation-->>Client: terminal outcome

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 2.94% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 34 functions across 1 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding an example for durable reservation idempotency.
Description check	✅ Passed	The description directly explains the idempotency, retry, crash-recovery, and deduplication goals of the changeset.
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.

Full details: Docstring Coverage

Explanation

Docstring coverage is 2.94% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 34 functions across 1 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch yordis/feat-operation-stream-idempotency-example

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit reads each line,
The patch grows clear beneath the moon,
Small changes hop in place,
Tests guard the garden path,
Reviews bloom before the dawn.}

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