fix(flags): handle empty evaluation key scopes

[marandaneto]

💡 Motivation and Context

sdk-specs#47 defines how SDKs should distinguish an empty feature flag evaluation scope from an omitted scope. The Ruby SDK previously treated flag_keys: [] like no scope and evaluated every available flag.

This change makes the three cases explicit:

• When flag_keys is omitted or nil, evaluation remains unscoped and all available flags are evaluated.
• When flag_keys is an empty array, evaluate_flags returns an empty snapshot without loading local flag definitions or calling /flags.
• When flag_keys contains keys, the existing scoped behavior remains unchanged and only those keys are requested and evaluated.

The returned empty snapshot remains usable. Accessing a missing key returns the normal missing-flag result and records the normal access event.

💚 How did you test it?

• BUNDLE_PATH=/tmp/posthog-ruby-bundle bundle exec rspec spec/posthog/feature_flag_evaluations_spec.rb - passed with 48 examples and 0 failures.
• BUNDLE_PATH=/tmp/posthog-ruby-bundle bundle exec rubocop - passed with 84 files inspected and no offenses.
• BUNDLE_PATH=/tmp/posthog-ruby-bundle bundle exec ruby -c lib/posthog/client.rb && BUNDLE_PATH=/tmp/posthog-ruby-bundle bundle exec ruby -c spec/posthog/feature_flag_evaluations_spec.rb - both syntax checks passed.
• BUNDLE_PATH=/tmp/posthog-ruby-bundle bundle exec rake public_api:check - passed.
• git diff --check origin/main...HEAD - passed.

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Added a patch changeset for posthog-ruby.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Pi coding agent (worker) prepared the existing implementation for review and opened this PR using the PR and autoreview skills. The local Pi session has no shareable URL. The agent added the required patch changeset, reran the Ruby validation, and reviewed the committed branch against origin/main. No review findings required code changes.

[github-actions]

posthog-ruby Compliance Report

Date: 2026-08-25 11:02:12 UTC
Duration: 98420ms

✅ All Tests Passed!

46/46 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	109ms
Format Validation.Event Has Uuid	✅	106ms
Format Validation.Event Has Lib Properties	✅	108ms
Format Validation.Distinct Id Is String	✅	108ms
Format Validation.Token Is Present	✅	106ms
Format Validation.Custom Properties Preserved	✅	108ms
Format Validation.Event Has Timestamp	✅	108ms
Retry Behavior.Retries On 503	✅	5414ms
Retry Behavior.Does Not Retry On 400	✅	2109ms
Retry Behavior.Does Not Retry On 401	✅	2109ms
Retry Behavior.Respects Retry After Header	✅	8015ms
Retry Behavior.Implements Backoff	✅	15719ms
Retry Behavior.Retries On 500	✅	5213ms
Retry Behavior.Retries On 502	✅	5210ms
Retry Behavior.Retries On 504	✅	5212ms
Retry Behavior.Max Retries Respected	✅	15522ms
Deduplication.Generates Unique Uuids	✅	112ms
Deduplication.Preserves Uuid On Retry	✅	5211ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10318ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5217ms
Deduplication.No Duplicate Events In Batch	✅	112ms
Deduplication.Different Events Have Different Uuids	✅	108ms
Compression.Sends Gzip When Enabled	✅	106ms
Batch Format.Uses Proper Batch Structure	✅	107ms
Batch Format.Flush With No Events Sends Nothing	✅	4ms
Batch Format.Multiple Events Batched Together	✅	111ms
Error Handling.Does Not Retry On 403	✅	2108ms
Error Handling.Does Not Retry On 413	✅	2109ms
Error Handling.Retries On 408	✅	5212ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	108ms
Request Payload.Flags Request Uses V2 Query Param	✅	107ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	109ms
Request Payload.Flags Request Omits Authorization Header	✅	108ms
Request Payload.Token In Flags Body Matches Init	✅	109ms
Request Payload.Groups Round Trip	✅	108ms
Request Payload.Groups Default To Empty Object	✅	107ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	107ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	107ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	107ms
Request Lifecycle.No Flags Request On Init Alone	✅	4ms
Request Lifecycle.No Flags Request On Normal Capture	✅	106ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	111ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	107ms
Retry Behavior.Retries Flags On 502	✅	247ms
Retry Behavior.Retries Flags On 504	✅	250ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	109ms

[greptile-apps]

_{Reviews (1): Last reviewed commit: "fix(flags): handle empty evaluation key ..." | Re-trigger Greptile}

[turnipdabeets]

Matches sdk-specs#47. flag_keys && flag_keys.empty? keeps nil unscoped, and asserting that the flag_missing event still fires is a good check that the empty snapshot stays usable rather than inert.