[yordis]

• Operators need to know that the lock guarantees ownership of progress rather than exclusive handler execution, that handlers must stay idempotent, and that the migration has to run before rolling nodes to the new version.

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[cursor]

PR Summary

Low Risk
Documentation-only changes with no runtime or schema impact.

Overview
Documentation-only update clarifying what subscription advisory locks actually guarantee in clustered EventStore deployments.

Architecture now explains that lock loss is detected after the fact, so checkpoint writes are fenced with a per-subscription lock generation in the subscriptions table—stale generations are rejected so a node that lost the lock learns it no longer owns progress.

Cluster expands on subscription behavior: the lock controls who may record progress, not exclusive handler execution, so two nodes can briefly process the same events during hand-off. It describes generation bumps on lock acquisition, rejected checkpoints for the old owner, and the requirement that subscribers stay idempotent (at-least-once). Mixed-version clusters only get this protection once every node records lock generations.

Upgrades adds migrate before rolling nodes: new-version nodes cannot acquire subscription locks until the schema migration runs (they retry); older nodes remain compatible with the migrated schema, enabling safe rolling upgrades after migration.

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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 1144113a-14d2-4a6b-bf9b-4199746f894d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

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