feat: add wrong_expected_version span event to aggregate execute OTel

[yordis]

Tracks wrong_expected_version count in the aggregate struct, exposes it via telemetry :stop metadata, and records a span event with the count on the OTel execute span when > 0.

• Add wrong_expected_version_count to %Aggregate{} struct
• Include count in :stop telemetry metadata
• OTel :stop handler adds span event when count > 0
• Add commanded_wrong_expected_version_count to CommandedAttributes

[cursor]

PR Summary

Medium Risk
Touches core aggregate command execution flow by adding state and metadata tracking for optimistic concurrency conflicts, which could affect telemetry and retry behavior if incorrect. Functional behavior should remain unchanged, but instrumentation is emitted on every aggregate execution.

Overview
Adds per-command tracking of wrong_expected_version conflicts to Commanded.Aggregates.Aggregate (wrong_expected_version_count), resets it at command start, increments on each :wrong_expected_version, and includes it in [:commanded, :aggregate, :execute, :stop] telemetry metadata.

Updates OpenTelemetry aggregate execute stop handling to record a commanded.aggregate.wrong_expected_version span event (with count + aggregate identifiers) when conflicts occurred, adds a new commanded.wrong_expected_version.count attribute constant, and extends tests/docs to cover the new metadata and span event behavior.

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

[coderabbitai]

Warning

Rate limit exceeded

@yordis has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 6 minutes and 7 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 51f25927-86ed-4cd8-a07d-1b7f4a86fc3e

📥 Commits

Reviewing files that changed from the base of the PR and between 174de8b and 10c250a.

📒 Files selected for processing (7)

• guides/explanations/fork-differences.md
• lib/commanded/aggregates/aggregate.ex
• lib/commanded/opentelemetry/aggregate.ex
• lib/commanded/opentelemetry/commanded_attributes.ex
• test/aggregates/aggregate_telemetry_test.exs
• test/commands/correlation_causation_test.exs
• test/opentelemetry/aggregate_test.exs

Walkthrough

Adds a new wrong_expected_version_count field to track version mismatch conflicts during command execution. The counter resets at each command attempt, increments on version mismatches, and propagates through telemetry metadata. An OpenTelemetry event and attribute accessor expose this metric for observability.

Changes

Cohort / File(s)	Summary
Aggregate State Tracking lib/commanded/aggregates/aggregate.ex	Introduces wrong_expected_version_count field (default 0) to Aggregate state. Resets counter at command start, increments on version mismatch, and includes in telemetry metadata propagation.
OpenTelemetry Instrumentation lib/commanded/opentelemetry/aggregate.ex, lib/commanded/opentelemetry/commanded_attributes.ex	Emits OTEL "wrong_expected_version" span event when count exceeds zero with aggregate version and UUID attributes. Adds public commanded_wrong_expected_version_count() attribute accessor.
Test Updates test/aggregates/aggregate_telemetry_test.exs, test/opentelemetry/aggregate_test.exs	Verifies stop event carries wrong_expected_version_count in metadata. Aliases OpenTelemetry Aggregate module and MockEventStore for test instrumentation validation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: implement OpenTelemetry instrumentation for aggregates #45: Directly extends OpenTelemetry aggregate instrumentation with wrong_expected_version event emission and attribute helpers in the same modules.

Poem

🐰 A counter hops through every command,
Tallying mismatch conflicts brand new,
Telemetry traces the journey at hand—
Each version dance now observable too! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the main change: adding a span event for wrong_expected_version tracking to aggregate execute OTel telemetry.
Description check	✅ Passed	The description clearly relates to the changeset, providing specific details about tracking wrong_expected_version counts in the aggregate struct, exposing via telemetry, and recording OTel events.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch wrong-expected-version

📝 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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@test/opentelemetry/aggregate_test.exs`:
- Line 26: There's a typo calling the non-existent module OTelOTelAggregate in
the test; replace the incorrect module name with OTelAggregate so the call
OTelOTelAggregate.setup() becomes OTelAggregate.setup(). Update the test
reference to use the correct module symbol OTelAggregate to fix the compilation
error.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: cc3d0514-98c5-425d-97ee-e16d55bbab19

📥 Commits

Reviewing files that changed from the base of the PR and between cb72033 and 174de8b.

📒 Files selected for processing (5)

• lib/commanded/aggregates/aggregate.ex
• lib/commanded/opentelemetry/aggregate.ex
• lib/commanded/opentelemetry/commanded_attributes.ex
• test/aggregates/aggregate_telemetry_test.exs
• test/opentelemetry/aggregate_test.exs

[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.}