feat: add v1alpha1 Consistency pattern for read-after-write

[yordis]

Add trogon.consistency.v1alpha1 package for implementing read-after-write
consistency in eventual consistency systems (CQRS/Event Sourcing).

Features:

• MinVersion mode: wait for projection >= required version (read-your-writes)
• ExactVersion mode: wait for projection == required version (strict snapshots)
• Configurable timeout_duration and delay_duration
• Server-side retry logic with version checking
• Comprehensive documentation with examples and trade-offs

Inspired by SpiceDB's consistency patterns (at_least_as_fresh, at_exact_snapshot).

Use case: Enable clients to immediately read their own writes despite
projection lag in CQRS systems by specifying minimum version requirements
from mutation responses.

Signed-off-by: Yordis Prieto yordis.prieto@gmail.com

[cursor]

PR Summary

Low Risk
Adds new Protobuf definitions and documentation only, with no runtime logic changes; risk is limited to potential downstream API adoption/compatibility considerations once generated code is used.

Overview
Introduces a new trogon.consistency.v1alpha1 Protobuf API (Consistency, MinVersion, ExactVersion) to let clients request read-after-write consistency via version-based requirements plus configurable timeout_duration/delay_duration.

Adds a dedicated doc (docs/explanation/consistency-pattern.md) describing recommended usage, server retry/error-handling guidance, and operational trade-offs.

^{Written by Cursor Bugbot for commit 7f0ac49. This will update automatically on new commits. Configure here.}

[coderabbitai]

Walkthrough

This pull request introduces a read-after-write consistency pattern for CQRS and Event Sourcing systems. It adds a Protobuf definition file introducing Consistency, MinVersion, and ExactVersion messages, along with comprehensive documentation describing usage, implementation guidelines, and trade-offs.

Changes

Cohort / File(s)	Summary
Protobuf Consistency Definitions proto/trogon/consistency/v1alpha1/consistency.proto	Introduces three new messages: Consistency (with oneof requirement for MinVersion or ExactVersion, plus optional timeout/delay durations), MinVersion (waits until projection.version >= specified version), and ExactVersion (waits until projection.version == specified version). Includes server implementation guidance and error handling semantics.
Consistency Pattern Documentation docs/explanation/consistency-pattern.md	Comprehensive guide detailing the read-after-write consistency pattern, including usage flows, comparison matrix between MinVersion and ExactVersion modes, server implementation requirements (retry logic, limits, error handling), observability practices (metrics, logging, tracing), and guidance on pattern applicability.

Sequence Diagram(s)

sequenceDiagram
    actor Client
    participant Server
    participant Projection
    
    Client->>Server: Mutation request
    Server->>Server: Process mutation
    Server-->>Client: Response + stream_version
    
    Client->>Server: Query + Consistency(stream_version)
    Server->>Projection: Check projection.version
    
    alt projection.version >= stream_version
        Server-->>Client: Return result
    else version mismatch
        Server->>Server: Retry with backoff
        Server->>Projection: Check projection.version again
        Server-->>Client: Return result (after catch-up)
    else timeout exceeded
        Server-->>Client: Unavailable error
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A consistency tale

Mutations bloom with versions bright,
Queries follow, seeking sight,
MinVersion waits, ExactVersion's night,
Projections catch up, all feels right! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly relates to the changeset, detailing the MinVersion/ExactVersion modes, timeout/delay configurations, and the use case for read-after-write consistency in CQRS systems.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a v1alpha1 Consistency pattern for read-after-write scenarios to support eventual consistency systems.

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

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch add-consistent

📝 Coding Plan

• Generate coding plan for human review comments

---

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 and usage tips.}

[github-actions]

The latest Buf updates on your PR. Results from workflow Buf CI / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	✅ passed	Mar 14, 2026, 4:40 AM

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}