feat: warn that payload filtering has no effect with FDv2

[beekld]

Documents and warns that payload_filter_key has no effect when the FDv2 data system is used.

Closes SDK-2975.

• Config#payload_filter_key docs now state payload filtering is unsupported with FDv2
• The FDv2 data system logs a warning at construction when a filter key is configured
• FDv1 behavior is unchanged; the shared option is not deprecated, since FDv1 still supports it

Requirements

• I have added test coverage for new or changed functionality
• I have followed the repository's pull request submission guidelines
• I have validated my changes against all supported platform versions

Related issues

SDK-2975, part of SDK-2575. Same change as java-core#209, go-server-sdk#440 and python-server-sdk#518, adapted for the shared option.

Implementation details

Unlike Go and Java, Ruby has no FDv2-specific filter setter — payload_filter_key is a top-level option shared by FDv1 and FDv2 — so it cannot be deprecated without also deprecating supported FDv1 usage. Instead the attr_reader docs call out the FDv2 limitation and Impl::DataSystem::FDv2#initialize warns once when the option is set.

The FDv2 initializers/synchronizers still append ?filter= to their requests. That is intentional for now: on the delivery side, FDv2 reads the filter query param only for observability and never uses it to select a payload, so the parameter is inert rather than harmful. Dropping it would also break the environment_filter_key contract-test scenarios that the pinned harness (v3.0.0-alpha.6) still runs, requiring suppressions until the harness pin is bumped past sdk-test-harness#431. Removing the parameter belongs with that bump in the removal phase.

Testing: rubocop clean; rspec spec/impl/data_system/fdv2_datasystem_spec.rb. Note two FDv1-fallback examples in that file fail on main as well under some random seeds (mock doubles leaking across examples) — unrelated to this change.

Link to Devin session: https://app.devin.ai/sessions/ed604c6db94d452ea9f2dc35d6acc398
Open in Devin Desktop: https://app.devin.ai/desktop/session/ed604c6db94d452ea9f2dc35d6acc398?variant=devin
Requested by: @beekld

---

Note

Overview
Clarifies that payload_filter_key does not apply when the FDv2 data system is in use, and surfaces that at runtime so misconfiguration is visible.

Config documentation for payload_filter_key now states that payload filtering is unsupported with FDv2 and has no effect on FDv2 requests. Impl::DataSystem::FDv2 logs a warning during construction when a filter key is set; FDv1 streaming/polling behavior is unchanged and the option is not deprecated.

Specs assert the warning is emitted only when payload_filter_key is configured.

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

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

The build-linux (jruby-9.4) failure is unrelated to this change: spec/impl/data_system/fdv2_datasystem_spec.rb is timing-flaky. Running that spec file on origin/main (af79a96, no changes from this branch) fails too, with a different pair of examples each run:

16 examples, 2 failures
rspec ./spec/impl/data_system/fdv2_datasystem_spec.rb:469 # ... does not fall back to FDv1 when fallback_to_fdv1 is false
rspec ./spec/impl/data_system/fdv2_datasystem_spec.rb:266 # ... shuts down data source when both primary and secondary fail

The two examples added by this PR pass consistently. I don't have permission to re-run the failed job; a maintainer re-run should clear it.