feat(examples): demonstrate idempotent appends

[yordis]

• Event IDs do not provide stream-wide uniqueness, which makes retry semantics easy to misuse for inventory operations.
• Executable evidence keeps client guidance aligned with the server concurrency guarantees.

[cursor]

PR Summary

Low Risk
Adds examples and integration tests only; no production client or server code paths are modified.

Overview
Adds an idempotent_reservation runnable example that shows durable retries for inventory reservations: reuse the same event ID and pin StreamState::StreamRevision to the revision from the prior successful append, so a duplicate append does not write twice.

Introduces trogon-eventstore/tests/api/idempotency.rs integration coverage for append idempotency (no-stream and explicit-revision retries, payload ignored on retry, same ID at another revision creates a new event, IDs not unique across streams) and wires it as single_node_idempotency in the integration harness and GitHub Actions matrix. The examples crate gains tokio and registers the new example target.

No changes to the client library implementation—only executable guidance and CI-backed behavior checks.

^{Reviewed by Cursor Bugbot for commit 6603020. 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: 0fa4a11e-1eca-4969-be19-dcfd5c3b2874

📥 Commits

Reviewing files that changed from the base of the PR and between f309717 and 6603020.

📒 Files selected for processing (6)

• .github/workflows/integration.yml
• examples/Cargo.toml
• examples/idempotent_reservation.rs
• trogon-eventstore/tests/api/idempotency.rs
• trogon-eventstore/tests/api/mod.rs
• trogon-eventstore/tests/integration.rs

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

---

Walkthrough

The change adds API tests for append idempotency, wires them into single-node integration tests, and adds an executable reservation example that retries the same event.

Changes

Append idempotency

Layer / File(s)	Summary
Idempotency scenarios trogon-eventstore/tests/api/idempotency.rs, trogon-eventstore/tests/api/mod.rs	Adds tests for repeated appends, payload changes, stream revisions, and event IDs across streams.
Single-node integration wiring trogon-eventstore/tests/integration.rs, .github/workflows/integration.yml	Registers the idempotency suite, adds a single-node integration test, and includes it in the CI matrix.
Reservation example examples/Cargo.toml, examples/idempotent_reservation.rs	Adds an async example that retries a reservation append and verifies the resulting stream contents.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: 🟡 Moderate · up to 66030

The reservation example documents retry behavior but cannot be run as a Cargo example in its current static library configuration, leaving the intended executable guidance unverified. Resolve the target configuration before merge.

Sequence Diagram(s)

sequenceDiagram
  participant Example
  participant TrogonEventstore
  participant InventoryStream
  Example->>TrogonEventstore: Create inventory-created event
  TrogonEventstore->>InventoryStream: Store initial event
  Example->>TrogonEventstore: Append inventory-reserved event
  TrogonEventstore->>InventoryStream: Store reservation event
  Example->>TrogonEventstore: Retry same event ID and revision
  TrogonEventstore-->>Example: Return same write result
  Example->>TrogonEventstore: Read stream
  TrogonEventstore-->>Example: Return two events

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.08% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 4 files. (2 skipped: …	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 summarizes the main change: adding an example that demonstrates idempotent appends.
Description check	✅ Passed	The description relates directly to event ID uniqueness, retry semantics, and the executable example added by the pull request.
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 23.08% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 4 files. (2 skipped: 2 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-idempotent-event-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 retries one event in flight
The stream keeps two records just right
Same ID, same result
No duplicate built
Tests guard the behavior tonight}

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