feat(compatibility): protect client interoperability

[yordis]

• Client releases need direct evidence that the supported C# surface remains interoperable with the server and Rust client.
• Compatibility regressions need to be caught before consumers discover them after release.

[cursor]

PR Summary

Medium Risk
Changes tracing semantics (span kind, parent/link model) and metadata persistence, which may affect downstream observability pipelines; compatibility harness is additive test infrastructure with limited production surface.

Overview
Adds a TrogonEventStore.Client.Compatibility CLI harness that exercises write, batch-write, read, subscribe, and persistent-subscription flows against a live server, emits JSON results, optionally signals readiness via a file, and exports OTLP traces. CI unit-test filtering now includes Compatibility.* tests, with coverage for command parsing, env options, and write credential handling.

Subscription OpenTelemetry semantics shift from consumer process spans to client receive spans (registry + generated SubscriptionTraceSemantics). Receive activities are created when subscription messages are enumerated (not in the gRPC pump), parented to the ambient subscriber context, and link to the remote append/producer span when traceparent is present in event metadata.

Metadata injection now only persists traceparent and tracestate into JSON metadata (baggage is not written on inject); receive spans still apply baggage from extracted message metadata. Diagnostics tests were updated for links, link-event edge cases, and the new receive behavior.

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

[coderabbitai]

Warning

Review limit reached

Next included review available in 43 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6f0e4beb-e8a1-4bfc-945c-c54b05bb1361

📥 Commits

Reviewing files that changed from the base of the PR and between fc8c2d7 and c142606.

📒 Files selected for processing (2)

• src/KurrentDB.Client/Core/Common/Diagnostics/ActivitySourceExtensions.cs
• test/KurrentDB.Client.Tests/Diagnostics/StreamsTracingInstrumentationTests.cs

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d4114fd9-f974-4f46-861f-f15927164397

📥 Commits

Reviewing files that changed from the base of the PR and between a904920 and fc8c2d7.

⛔ Files ignored due to path filters (1)

• src/KurrentDB.Client/Core/Common/Diagnostics/Generated/SubscriptionTraceSemantics.g.cs is excluded by !**/generated/**

📒 Files selected for processing (14)

• compatibility/TrogonEventStore.Client.Compatibility/CompatibilityApplication.cs
• otel/semconv/registry/trogon/eventstore/client/spans.yaml
• otel/semconv/templates/registry/csharp/subscription-trace-semantics.cs.j2
• otel/semconv/templates/registry/csharp/weaver.yaml
• src/KurrentDB.Client/Core/Common/Diagnostics/ActivitySourceExtensions.cs
• src/KurrentDB.Client/Core/Common/Diagnostics/EventMetadataExtensions.cs
• src/KurrentDB.Client/Core/Common/Diagnostics/Tracing/TracingConstants.cs
• src/KurrentDB.Client/PersistentSubscriptions/KurrentDBPersistentSubscriptionsClient.Read.cs
• src/KurrentDB.Client/Streams/KurrentDBClient.Subscriptions.cs
• test/KurrentDB.Client.Tests.Common/Fixtures/DiagnosticsFixture.cs
• test/KurrentDB.Client.Tests/Compatibility/CompatibilityApplicationTests.cs
• test/KurrentDB.Client.Tests/Diagnostics/OpenTelemetryIntegrationTests.cs
• test/KurrentDB.Client.Tests/Diagnostics/PersistentSubscriptionsTracingInstrumentationTests.cs
• test/KurrentDB.Client.Tests/Diagnostics/StreamsTracingInstrumentationTests.cs

💤 Files with no reviewable changes (1)

• src/KurrentDB.Client/Core/Common/Diagnostics/Tracing/TracingConstants.cs

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

---

Walkthrough

The pull request adds a compatibility executable for KurrentDB operations and updates subscription OpenTelemetry tracing. It also limits persisted propagation metadata to trace context fields and adds compatibility and diagnostics tests.

Changes

Compatibility CLI

Layer / File(s)	Summary
Command and configuration contracts compatibility/.../CompatibilityCommand.cs, compatibility/.../CompatibilityContract.cs, compatibility/.../CompatibilityEvent.cs, compatibility/.../CompatibilityOptions.cs, test/KurrentDB.Client.Tests/Compatibility/*	Defines compatibility commands, event payloads, constants, environment options, ready-file signaling, and tests for parsing and configuration.
KurrentDB compatibility operations compatibility/.../CompatibilityApplication.cs, test/KurrentDB.Client.Tests/Compatibility/CompatibilityApplicationTests.cs	Implements event writes, reads, subscriptions, persistent subscriptions, payload validation, result output, and credential handling validation.
Executable and telemetry wiring compatibility/.../TrogonEventStore.Client.Compatibility.csproj, compatibility/.../Program.cs, compatibility/.../CompatibilityProgram.cs, test/KurrentDB.Client.Tests/KurrentDB.Client.Tests.csproj, .github/workflows/dotnet.yml	Adds the executable entry point, OpenTelemetry configuration, timeout and exit-code handling, test-project wiring, and compatibility test filtering.

Subscription telemetry

Layer / File(s)	Summary
Propagation and tracing contracts src/KurrentDB.Client/Core/Common/Diagnostics/EventMetadataExtensions.cs, src/KurrentDB.Client/Core/Common/Diagnostics/Tracing/TracingConstants.cs, otel/semconv/registry/..., otel/semconv/templates/...	Persists only traceparent and tracestate, removes the process operation, and generates receive-span semantics.
Subscription receive activity implementation src/KurrentDB.Client/Core/Common/Diagnostics/ActivitySourceExtensions.cs, src/KurrentDB.Client/Streams/KurrentDBClient.Subscriptions.cs, src/KurrentDB.Client/PersistentSubscriptions/KurrentDBPersistentSubscriptionsClient.Read.cs	Moves tracing to message enumeration and creates receive activities with ambient parents, producer links, propagation baggage, and explicit start times.
Subscription telemetry validation test/KurrentDB.Client.Tests.Common/Fixtures/DiagnosticsFixture.cs, test/KurrentDB.Client.Tests/Diagnostics/*	Updates assertions for receive-span semantics, parent and link relationships, propagation behavior, and resolved events.

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

Merge Risk: 🟡 Moderate · up to fc8c2

The compatibility gate now creates durable server state and uses acknowledgements as release evidence. It can acknowledge a nonmatching event before validation or lose evidence after interruption, causing concurrent or retried runs to produce incomplete or misleading results; batch writes may also attempt unauthenticated requests when credentials are absent. Merge readiness is moderate until acknowledgement and recovery behavior are fixed or explicitly accepted with appropriate authorization and cleanup controls.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant CompatibilityProgram
  participant CompatibilityApplication
  participant KurrentDB
  participant OTLPExporter

  Client->>CompatibilityProgram: command-line arguments and environment
  CompatibilityProgram->>CompatibilityApplication: execute parsed command
  CompatibilityApplication->>KurrentDB: write, read, subscribe, or consume event
  KurrentDB-->>CompatibilityApplication: event data or subscription confirmation
  CompatibilityApplication-->>CompatibilityProgram: compatibility result
  CompatibilityProgram->>OTLPExporter: force-flush telemetry
  CompatibilityProgram-->>Client: exit code

Loading

Poem

A rabbit checked the stream at dawn
Commands hopped neatly onward
Events wore a run ID bright
Telemetry traced the night
The ready file appeared just right

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description directly states that the changes provide interoperability evidence and detect compatibility regressions before release. This matches the compatibility project, compatibility tests, and…
Title check	✅ Passed	The title clearly identifies the main change as protecting client interoperability through compatibility work. It is concise and related to 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: Description check

Explanation

The description directly states that the changes provide interoperability evidence and detect compatibility regressions before release. This matches the compatibility project, compatibility tests, and workflow updates.

Full details: Docstring Coverage

Explanation

Docstring coverage is 3.03% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 66 functions across 18 files. (3 skipped: 3 unsupported.)

✨ 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-client-compatibility-gate

---

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

[cursor]

Cursor Bugbot has reviewed your changes using default effort 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.}

^{Reviewed by Cursor Bugbot for commit 58cf503. Configure here.}